1# How to contribute 2 3We'd love to accept your patches and contributions to this project. There are 4just a few small guidelines you need to follow. 5 6## Getting started 7 8Before we can work on the code, we need to get a copy of it and setup some 9local environment and tools. 10 11First, fork the code to your user and clone your fork. This gives you a private 12playground where you can do any edits you'd like. For this guide, we'll use 13the [GitHub `gh` tool](https://github.com/cli/cli) 14([Linux install](https://github.com/cli/cli/blob/trunk/docs/install_linux.md)). 15(More advanced users may prefer the GitHub UI and raw `git` commands). 16 17```shell 18gh repo fork bazelbuild/rules_python --clone --remote 19``` 20 21Next, make sure you have a new enough version of Python installed that supports the 22various code formatters and other devtools. For a quick start, 23[install pyenv](https://github.com/pyenv/pyenv-installer) and 24at least Python 3.9.15: 25 26```shell 27curl https://pyenv.run | bash 28pyenv install 3.9.15 29pyenv shell 3.9.15 30``` 31 32## Development workflow 33 34It's suggested that you create what is called a "feature/topic branch" in your 35fork when you begin working on code you want to eventually send or code review. 36 37``` 38git checkout main # Start our branch from the latest code 39git checkout -b my-feature # Create and switch to our feature branch 40git push origin my-feature # Cause the branch to be created in your fork. 41``` 42 43From here, you then edit code and commit to your local branch. If you want to 44save your work to github, you use `git push` to do so: 45 46``` 47git push origin my-feature 48``` 49 50Once the code is in your github repo, you can then turn it into a Pull Request 51to the actual rules_python project and begin the code review process. 52 53 54## Running tests 55 56Running tests is particularly easy thanks to Bazel, simply run: 57 58``` 59bazel test //... 60``` 61 62And it will run all the tests it can find. The first time you do this, it will 63probably take long time because various dependencies will need to be downloaded 64and setup. Subsequent runs will be faster, but there are many tests, and some of 65them are slow. If you're working on a particular area of code, you can run just 66the tests in those directories instead, which can speed up your edit-run cycle. 67 68Note that there are tests to verify generated documentation is correct -- if 69you're modifying the signature of a public function, these tests will likely 70fail and you'll need to [regenerate the api docs](#documentation). 71 72## Formatting 73 74Starlark files should be formatted by 75[buildifier](https://github.com/bazelbuild/buildtools/blob/master/buildifier/README.md). 76Otherwise the Buildkite CI will fail with formatting/linting violations. 77We suggest using a pre-commit hook to automate this. 78First [install pre-commit](https://pre-commit.com/#installation), 79then run 80 81```shell 82pre-commit install 83``` 84 85### Running buildifer manually 86 87You can also run buildifier manually. To do this, 88[install buildifier](https://github.com/bazelbuild/buildtools/blob/master/buildifier/README.md), 89and run the following command: 90 91```shell 92$ buildifier --lint=fix --warnings=native-py -warnings=all WORKSPACE 93``` 94 95Replace the argument "WORKSPACE" with the file that you are linting. 96 97## Contributor License Agreement 98 99Contributions to this project must be accompanied by a Contributor License 100Agreement. You (or your employer) retain the copyright to your contribution, 101this simply gives us permission to use and redistribute your contributions as 102part of the project. Head over to <https://cla.developers.google.com/> to see 103your current agreements on file or to sign a new one. 104 105You generally only need to submit a CLA once, so if you've already submitted one 106(even if it was for a different project), you probably don't need to do it 107again. 108 109## Code reviews 110 111All submissions, including submissions by project members, require review. We 112use GitHub pull requests for this purpose. Consult [GitHub Help] for more 113information on using pull requests. 114 115[GitHub Help]: https://help.github.com/articles/about-pull-requests/ 116 117### Commit messages 118 119Commit messages (upon merging) and PR messages should follow the [Conventional 120Commits](https://www.conventionalcommits.org/) style: 121 122``` 123type(scope)!: <summary> 124 125<body> 126 127BREAKING CHANGE: <summary> 128``` 129 130Where `(scope)` is optional, and `!` is only required if there is a breaking change. 131If a breaking change is introduced, then `BREAKING CHANGE:` is required. 132 133Common `type`s: 134 135* `build:` means it affects the building or development workflow. 136* `docs:` means only documentation is being added, updated, or fixed. 137* `feat:` means a user-visible feature is being added. 138* `fix:` means a user-visible behavior is being fixed. 139* `refactor:` means some sort of code cleanup that doesn't change user-visible behavior. 140* `revert:` means a prior change is being reverted in some way. 141* `test:` means only tests are being added. 142 143For the full details of types, see 144[Conventional Commits](https://www.conventionalcommits.org/). 145 146## Generated files 147 148Some checked-in files are generated and need to be updated when a new PR is 149merged. 150 151### Documentation 152 153To regenerate the content under the `docs/` directory, run this command: 154 155```shell 156bazel run //docs:update 157``` 158 159This needs to be done whenever the docstrings in the corresponding .bzl files 160are changed; a test failure will remind you to run this command when needed. 161 162## Core rules 163 164The bulk of this repo is owned and maintained by the Bazel Python community. 165However, since the core Python rules (`py_binary` and friends) are still 166bundled with Bazel itself, the Bazel team retains ownership of their stubs in 167this repository. This will be the case at least until the Python rules are 168fully migrated to Starlark code. 169 170Practically, this means that a Bazel team member should approve any PR 171concerning the core Python logic. This includes everything under the `python/` 172directory except for `pip.bzl` and `requirements.txt`. 173 174Issues should be triaged as follows: 175 176- Anything concerning the way Bazel implements the core Python rules should be 177 filed under [bazelbuild/bazel](https://github.com/bazelbuild/bazel), using 178 the label `team-Rules-python`. 179 180- If the issue specifically concerns the rules_python stubs, it should be filed 181 here in this repository and use the label `core-rules`. 182 183- Anything else, such as feature requests not related to existing core rules 184 functionality, should also be filed in this repository but without the 185 `core-rules` label. 186 187## FAQ 188 189### Installation errors when during `git commit` 190 191If you did `pre-commit install`, various tools are run when you do `git commit`. 192This might show as an error such as: 193 194``` 195[INFO] Installing environment for https://github.com/psf/black. 196[INFO] Once installed this environment will be reused. 197[INFO] This may take a few minutes... 198An unexpected error has occurred: CalledProcessError: command: ... 199``` 200 201To fix, you'll need to figure out what command is failing and why. Because these 202are tools that run locally, its likely you'll need to fix something with your 203environment or the installation of the tools. For Python tools (e.g. black or 204isort), you can try using a different Python version in your shell by using 205tools such as [pyenv](https://github.com/pyenv/pyenv). 206