|
| 1 | +# CONTRIBUTING |
| 2 | + |
| 3 | +## Contributing to Dubbo Python |
| 4 | + |
| 5 | +Dubbo Python is released under the non-restrictive Apache 2.0 licenses and follows a very standard Github development process, using Github tracker for issues and merging pull requests into main. Contributions of all form to this repository is acceptable, as long as it follows the prescribed community guidelines enumerated below. |
| 6 | + |
| 7 | +### Sign the Contributor License Agreement |
| 8 | + |
| 9 | +Before we accept a non-trivial patch or pull request (PRs), we will need you to sign the Contributor License Agreement. Signing the contributors' agreement does not grant anyone commits rights to the main repository, but it does mean that we can accept your contributions, and you will get an author credit if we do. Active contributors may get invited to join the core team that will grant them privileges to merge existing PRs. |
| 10 | + |
| 11 | +### Contact |
| 12 | + |
| 13 | +### Mailing list |
| 14 | + |
| 15 | +The mailing list is the recommended way of pursuing a discussion on almost anything related to Dubbo. Please refer to this [guide](https://github.com/apache/dubbo/wiki/Mailing-list-subscription-guide) for detailed documentation on how to subscribe. |
| 16 | + |
| 17 | +- [[email protected]](mailto:[email protected]): the developer mailing list where you can ask questions about an issue you may have encountered while working with Dubbo. |
| 18 | +- [[email protected]](mailto:[email protected]): the commit updates will get broadcasted on this mailing list. You can subscribe to it, should you be interested in following Dubbo's development. |
| 19 | +- [[email protected]](mailto:[email protected]): all the Github [issue ](https://github.com/apache/dubbo/issues) updates and [pull request ](https://github.com/apache/dubbo/pulls) updates will be sent to this mailing list. |
| 20 | + |
| 21 | +### Reporting issue |
| 22 | + |
| 23 | +Please follow the [template](https://github.com/apache/dubbo/issues/new?template=dubbo-issue-report-template.md) for reporting any issues. |
| 24 | + |
| 25 | +NOTE: Issues related to Dubbo Python should be submitted in the [Dubbo](https://github.com/apache/dubbo/issues) repository, and the **Apache Dubbo Component** option should be set to `Python SDK`. |
| 26 | + |
| 27 | +### Code Conventions |
| 28 | + |
| 29 | +Our code style almost fully adheres to the [**PEP 8 style guide**](https://peps.python.org/pep-0008/), with the following adjustments and new constraints: |
| 30 | + |
| 31 | +1. We have relaxed the **Maximum Line Length** limit from 79 to **120**. |
| 32 | +2. For **Documentation Strings**, or **comment style**, we follow the `reStructuredText` format. |
| 33 | +3. ... |
| 34 | + |
| 35 | +### Contribution flow |
| 36 | + |
| 37 | +A rough outline of an ideal contributors' workflow is as follows: |
| 38 | + |
| 39 | +- Fork the current repository |
| 40 | +- Create a topic branch from where to base the contribution. Mostly, it's the main branch. |
| 41 | +- Make commits of logical units. |
| 42 | +- Make sure the commit messages are in the proper format (see below). |
| 43 | +- Push changes in a topic branch to your forked repository. |
| 44 | +- Follow the checklist in the [pull request template](https://github.com/apache/dubbo-python/blob/main/.github/PULL_REQUEST_TEMPLATE.md) |
| 45 | +- Before sending out the pull request, please sync your forked repository with the remote repository to ensure that your PR is elegant, concise. Reference the guide below: |
| 46 | + |
| 47 | +``` |
| 48 | +git remote add upstream [email protected]:apache/dubbo-python.git |
| 49 | +git fetch upstream |
| 50 | +git rebase upstream/master |
| 51 | +git checkout -b your_awesome_patch |
| 52 | +... add some work |
| 53 | +git push origin your_awesome_patch |
| 54 | +
|
| 55 | +``` |
| 56 | + |
| 57 | +- Submit a pull request to apache/dubbo-python and wait for the reply. |
| 58 | + |
| 59 | +Thanks for contributing! |
| 60 | + |
| 61 | +### Code style |
| 62 | + |
| 63 | +We use **ruff** as the linter and code formatter for Dubbo-Python, and **Mypy** as the static type checker. |
| 64 | + |
| 65 | +Therefore, when developing, you should install both tools: |
| 66 | + |
| 67 | +- ruff: [https://github.com/astral-sh/ruff](https://github.com/astral-sh/ruff) |
| 68 | +- Mypy: [https://github.com/python/mypy](https://github.com/python/mypy) |
| 69 | + |
| 70 | +We have already set up the configurations for ruff and Mypy in the `pyproject.toml` file. You only need to specify the configuration path (`pyproject.toml`) when using them. |
| 71 | + |
| 72 | +1. Code Formatting |
| 73 | + |
| 74 | + By default, ruff will look for the `pyproject.toml` file in the current directory and its parent directories and load its configuration. |
| 75 | + |
| 76 | + ```bash |
| 77 | + # Default |
| 78 | + ruff format |
| 79 | + |
| 80 | + # Specify configuration file |
| 81 | + ruff format --config pyproject.toml |
| 82 | + ``` |
| 83 | + |
| 84 | +2. Code Linting |
| 85 | + |
| 86 | + ```bash |
| 87 | + # Just check |
| 88 | + ruff check |
| 89 | + |
| 90 | + # Check and fix |
| 91 | + ruff check --fix |
| 92 | + ``` |
| 93 | + |
| 94 | +3. Static Type Checking |
| 95 | + |
| 96 | + Mypy will also automatically look for the `pyproject.toml` file and load its configuration. |
| 97 | + |
| 98 | + ```bash |
| 99 | + # Default |
| 100 | + mypy |
| 101 | + |
| 102 | + # Specify configuration file |
| 103 | + mypy --config-file pyproject.toml |
| 104 | + ``` |
0 commit comments