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 68## Updating tool dependencies 69 70It's suggested to routinely update the tool versions within our repo - some of the 71tools are using requirement files compiled by `uv` and others use other means. In order 72to have everything self-documented, we have a special target - 73`//private:requirements.update`, which uses `rules_multirun` to run in sequence all 74of the requirement updating scripts in one go. This can be done once per release as 75we prepare for releases. 76 77## Formatting 78 79Starlark files should be formatted by 80[buildifier](https://github.com/bazelbuild/buildtools/blob/master/buildifier/README.md). 81Otherwise the Buildkite CI will fail with formatting/linting violations. 82We suggest using a pre-commit hook to automate this. 83First [install pre-commit](https://pre-commit.com/#installation), 84then run 85 86```shell 87pre-commit install 88``` 89 90### Running buildifer manually 91 92You can also run buildifier manually. To do this, 93[install buildifier](https://github.com/bazelbuild/buildtools/blob/master/buildifier/README.md), 94and run the following command: 95 96```shell 97$ buildifier --lint=fix --warnings=native-py -warnings=all WORKSPACE 98``` 99 100Replace the argument "WORKSPACE" with the file that you are linting. 101 102## Contributor License Agreement 103 104Contributions to this project must be accompanied by a Contributor License 105Agreement. You (or your employer) retain the copyright to your contribution, 106this simply gives us permission to use and redistribute your contributions as 107part of the project. Head over to <https://cla.developers.google.com/> to see 108your current agreements on file or to sign a new one. 109 110You generally only need to submit a CLA once, so if you've already submitted one 111(even if it was for a different project), you probably don't need to do it 112again. 113 114## Code reviews 115 116All submissions, including submissions by project members, require review. We 117use GitHub pull requests for this purpose. Consult [GitHub Help] for more 118information on using pull requests. 119 120[GitHub Help]: https://help.github.com/articles/about-pull-requests/ 121 122### Commit messages 123 124Commit messages (upon merging) and PR messages should follow the [Conventional 125Commits](https://www.conventionalcommits.org/) style: 126 127``` 128type(scope)!: <summary> 129 130<body> 131 132BREAKING CHANGE: <summary> 133``` 134 135Where `(scope)` is optional, and `!` is only required if there is a breaking change. 136If a breaking change is introduced, then `BREAKING CHANGE:` is required; see 137the [Breaking Changes](#breaking-changes) section for how to introduce breaking 138changes. 139 140Common `type`s: 141 142* `build:` means it affects the building or development workflow. 143* `docs:` means only documentation is being added, updated, or fixed. 144* `feat:` means a user-visible feature is being added. 145* `fix:` means a user-visible behavior is being fixed. 146* `refactor:` means some sort of code cleanup that doesn't change user-visible behavior. 147* `revert:` means a prior change is being reverted in some way. 148* `test:` means only tests are being added. 149 150For the full details of types, see 151[Conventional Commits](https://www.conventionalcommits.org/). 152 153## Generated files 154 155Some checked-in files are generated and need to be updated when a new PR is 156merged: 157 158* **requirements lock files**: These are usually generated by a 159 `compile_pip_requirements` update target, which is usually in the same directory. 160 e.g. `bazel run //docs:requirements.update` 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(breaking-changes)= 188## Breaking Changes 189 190Breaking changes are generally permitted, but we follow a 3-step process for 191introducing them. The intent behind this process is to balance the difficulty of 192version upgrades for users, maintaining multiple code paths, and being able to 193introduce modern functionality. 194 195The general process is: 196 1971. In version `N`, introduce the new behavior, but it must be disabled by 198 default. Users can opt into the new functionality when they upgrade to 199 version `N`, which lets them try it and verify functionality. 2002. In version `N+1`, the new behavior can be enabled by default. Users can 201 opt out if necessary, but doing so causes a warning to be issued. 2023. In version `N+2`, the new behavior is always enabled and cannot be opted out 203 of. The API for the control mechanism can be removed in this release. 204 205Note that the `+1` and `+2` releases are just examples; the steps are not 206required to happen in immediately subsequent releases. 207 208Once The first major version is released, the process will be: 2091. In `N.M.0` we introduce the new behaviour, but it is disabled by a feature flag. 2102. In `N.M+1.0` we may choose the behaviour to become the default if it is not too 211 disruptive. 2123. In `N+1.0.0` we get rid of the old behaviour. 213 214### How to control breaking changes 215 216The details of the control mechanism will depend on the situation. Below is 217a summary of some different options. 218 219* Environment variables are best for repository rule behavior. Environment 220 variables can be propagated to rules and macros using the generated 221 `@rules_python_internal//:config.bzl` file. 222* Attributes are applicable to macros and regular rules, especially when the 223 behavior is likely to vary on a per-target basis. 224* [User defined build settings](https://bazel.build/extending/config#user-defined-build-settings) 225 (aka custom build flags) are applicable for rules when the behavior change 226 generally wouldn't vary on a per-target basis. They also have the benefit that 227 an entire code base can have them easily enabled by a bazel command line flag. 228* Allowlists allow a project to centrally control if something is 229 enabled/disabled. Under the hood, they are basically a specialized custom 230 build flag. 231 232Note that attributes and flags can seamlessly interoperate by having the default 233controlled by a flag, and an attribute can override the flag setting. This 234allows a project to enable the new behavior by default while they work to fix 235problematic cases to prepare for the next upgrade. 236 237### What is considered a breaking change? 238 239Precisely defining what constitutes a breaking change is hard because it's 240easy for _someone, somewhere_ to depend on _some_ observable behavior, despite 241our best efforts to thoroughly document what is or isn't supported and hiding 242any internal details. 243 244In general, something is considered a breaking change when it changes the 245direct behavior of a supported public API. Simply being able to observe a 246behavior change doesn't necessarily mean it's a breaking change. 247 248Long standing undocumented behavior is a large grey area and really depends on 249how load-bearing it has become and what sort of reasonable expectation of 250behavior there is. 251 252Here's some examples of what would or wouldn't be considered a breaking change. 253 254Breaking changes: 255 * Renaming an function argument for public functions. 256 * Enforcing stricter validation than was previously required when there's a 257 sensible reason users would run afoul of it. 258 * Changing the name of a public rule. 259 260Not breaking changes: 261 * Upgrading dependencies 262 * Changing internal details, such as renaming an internal file. 263 * Changing a rule to a macro. 264 265## FAQ 266 267### Installation errors when during `git commit` 268 269If you did `pre-commit install`, various tools are run when you do `git commit`. 270This might show as an error such as: 271 272``` 273[INFO] Installing environment for https://github.com/psf/black. 274[INFO] Once installed this environment will be reused. 275[INFO] This may take a few minutes... 276An unexpected error has occurred: CalledProcessError: command: ... 277``` 278 279To fix, you'll need to figure out what command is failing and why. Because these 280are tools that run locally, its likely you'll need to fix something with your 281environment or the installation of the tools. For Python tools (e.g. black or 282isort), you can try using a different Python version in your shell by using 283tools such as [pyenv](https://github.com/pyenv/pyenv). 284