Bill Wendling | 113c43e | 2023-06-13 18:28:23 -0500 | [diff] [blame] | 1 | # How to Contribute |
Bill Wendling | 7d62345 | 2015-03-18 13:36:07 -0700 | [diff] [blame] | 2 | |
Bill Wendling | 113c43e | 2023-06-13 18:28:23 -0500 | [diff] [blame] | 3 | Want to contribute? Great! First, read this page (including the small print at |
| 4 | the end). |
Eli Bendersky | cd0aa2f | 2015-03-19 06:22:10 -0700 | [diff] [blame] | 5 | |
Bill Wendling | 113c43e | 2023-06-13 18:28:23 -0500 | [diff] [blame] | 6 | ## Before you contribute |
| 7 | |
| 8 | Before we can use your code, you must sign the [Google Individual Contributor |
| 9 | License Agreement](https://developers.google.com/open-source/cla/individual?csw=1) |
| 10 | (CLA), which you can do online. The CLA is necessary mainly because you own the |
Bill Wendling | 7d62345 | 2015-03-18 13:36:07 -0700 | [diff] [blame] | 11 | copyright to your changes, even after your contribution becomes part of our |
| 12 | codebase, so we need your permission to use and distribute your code. We also |
| 13 | need to be sure of various other things—for instance that you'll tell us if you |
| 14 | know that your code infringes on other people's patents. You don't have to sign |
| 15 | the CLA until after you've submitted your code for review and a member has |
| 16 | approved it, but you must do it before we can put your code into our codebase. |
| 17 | Before you start working on a larger contribution, you should get in touch with |
| 18 | us first through the issue tracker with your idea so that we can help out and |
| 19 | possibly guide you. Coordinating up front makes it much easier to avoid |
| 20 | frustration later on. |
| 21 | |
Bill Wendling | 113c43e | 2023-06-13 18:28:23 -0500 | [diff] [blame] | 22 | ## Code reviews |
Eli Bendersky | cd0aa2f | 2015-03-19 06:22:10 -0700 | [diff] [blame] | 23 | |
Bill Wendling | 7d62345 | 2015-03-18 13:36:07 -0700 | [diff] [blame] | 24 | All submissions, including submissions by project members, require review. We |
| 25 | use Github pull requests for this purpose. |
| 26 | |
Bill Wendling | 113c43e | 2023-06-13 18:28:23 -0500 | [diff] [blame] | 27 | ## YAPF coding style |
Eli Bendersky | cd0aa2f | 2015-03-19 06:22:10 -0700 | [diff] [blame] | 28 | |
Bill Wendling | 113c43e | 2023-06-13 18:28:23 -0500 | [diff] [blame] | 29 | YAPF follows the [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html) |
| 30 | with two exceptions: |
Sam Clegg | 4357fa3 | 2015-04-08 12:21:46 -0700 | [diff] [blame] | 31 | |
| 32 | - 2 spaces for indentation rather than 4. |
Bill Wendling | 113c43e | 2023-06-13 18:28:23 -0500 | [diff] [blame] | 33 | - CamelCase for function and method names rather than `snake_case`. |
Sam Clegg | 4357fa3 | 2015-04-08 12:21:46 -0700 | [diff] [blame] | 34 | |
Bill Wendling | cfcf45f | 2017-10-05 15:54:09 -0700 | [diff] [blame] | 35 | The rationale for this is that YAPF was initially developed at Google where |
| 36 | these two exceptions are still part of the internal Python style guide. |
Eli Bendersky | cd0aa2f | 2015-03-19 06:22:10 -0700 | [diff] [blame] | 37 | |
Kyle Gottfried | 276a919 | 2023-09-22 17:54:58 -0400 | [diff] [blame] | 38 | ## Getting started |
| 39 | YAPF supports using tox 3 for creating a local dev environment, testing, and |
| 40 | building redistributables. See [HACKING.md](HACKING.md) for more info. |
| 41 | |
| 42 | ```bash |
| 43 | $ pipx run --spec='tox<4' tox --devenv .venv |
| 44 | ``` |
| 45 | |
Bill Wendling | 113c43e | 2023-06-13 18:28:23 -0500 | [diff] [blame] | 46 | ## Small print |
Eli Bendersky | cd0aa2f | 2015-03-19 06:22:10 -0700 | [diff] [blame] | 47 | |
Bill Wendling | 7d62345 | 2015-03-18 13:36:07 -0700 | [diff] [blame] | 48 | Contributions made by corporations are covered by a different agreement than |
| 49 | the one above, the Software Grant and Corporate Contributor License Agreement. |