blob: 4c0273cd42d72b61ab52d49aba9922e4c7984f88 [file] [log] [blame] [view]
Bill Wendling113c43e2023-06-13 18:28:23 -05001# How to Contribute
Bill Wendling7d623452015-03-18 13:36:07 -07002
Bill Wendling113c43e2023-06-13 18:28:23 -05003Want to contribute? Great! First, read this page (including the small print at
4the end).
Eli Benderskycd0aa2f2015-03-19 06:22:10 -07005
Bill Wendling113c43e2023-06-13 18:28:23 -05006## Before you contribute
7
8Before we can use your code, you must sign the [Google Individual Contributor
9License 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 Wendling7d623452015-03-18 13:36:07 -070011copyright to your changes, even after your contribution becomes part of our
12codebase, so we need your permission to use and distribute your code. We also
13need to be sure of various other thingsfor instance that you'll tell us if you
14know that your code infringes on other people's patents. You don't have to sign
15the CLA until after you've submitted your code for review and a member has
16approved it, but you must do it before we can put your code into our codebase.
17Before you start working on a larger contribution, you should get in touch with
18us first through the issue tracker with your idea so that we can help out and
19possibly guide you. Coordinating up front makes it much easier to avoid
20frustration later on.
21
Bill Wendling113c43e2023-06-13 18:28:23 -050022## Code reviews
Eli Benderskycd0aa2f2015-03-19 06:22:10 -070023
Bill Wendling7d623452015-03-18 13:36:07 -070024All submissions, including submissions by project members, require review. We
25use Github pull requests for this purpose.
26
Bill Wendling113c43e2023-06-13 18:28:23 -050027## YAPF coding style
Eli Benderskycd0aa2f2015-03-19 06:22:10 -070028
Bill Wendling113c43e2023-06-13 18:28:23 -050029YAPF follows the [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html)
30with two exceptions:
Sam Clegg4357fa32015-04-08 12:21:46 -070031
32- 2 spaces for indentation rather than 4.
Bill Wendling113c43e2023-06-13 18:28:23 -050033- CamelCase for function and method names rather than `snake_case`.
Sam Clegg4357fa32015-04-08 12:21:46 -070034
Bill Wendlingcfcf45f2017-10-05 15:54:09 -070035The rationale for this is that YAPF was initially developed at Google where
36these two exceptions are still part of the internal Python style guide.
Eli Benderskycd0aa2f2015-03-19 06:22:10 -070037
Kyle Gottfried276a9192023-09-22 17:54:58 -040038## Getting started
39YAPF supports using tox 3 for creating a local dev environment, testing, and
40building redistributables. See [HACKING.md](HACKING.md) for more info.
41
42```bash
43$ pipx run --spec='tox<4' tox --devenv .venv
44```
45
Bill Wendling113c43e2023-06-13 18:28:23 -050046## Small print
Eli Benderskycd0aa2f2015-03-19 06:22:10 -070047
Bill Wendling7d623452015-03-18 13:36:07 -070048Contributions made by corporations are covered by a different agreement than
49the one above, the Software Grant and Corporate Contributor License Agreement.