# Dev Guide This document covers tips and guidance for working on the `rules_python` code base. Its primary audience is first-time contributors. ## Running tests Running tests is particularly easy thanks to Bazel, simply run: ``` bazel test //... ``` And it will run all the tests it can find. The first time you do this, it will probably take a long time because various dependencies will need to be downloaded and set up. Subsequent runs will be faster, but there are many tests, and some of them are slow. If you're working on a particular area of code, you can run just the tests in those directories instead, which can speed up your edit-run cycle. ## Writing Tests Most code should have tests of some sort. This helps us have confidence that refactors didn't break anything and that releases won't have regressions. We don't require 100% test coverage; testing certain Bazel functionality is difficult, and some edge cases are simply too hard to test or not worth the extra complexity. We try to judiciously decide when not having tests is a good idea. Tests go under `tests/`. They are loosely organized into directories for the particular subsystem or functionality they are testing. If an existing directory doesn't seem like a good match for the functionality being tested, then it's fine to create a new directory. Re-usable test helpers and support code go in `tests/support`. Tests don't need to be perfectly factored and not every common thing a test does needs to be factored into a more generally reusable piece. Copying and pasting is fine. It's more important for tests to balance understandability and maintainability. ### Test utilities General code to support testing is in {gh-path}`tests/support`. It has a variety of functions, constants, rules etc, to make testing easier. Below are some common utilities that are frequently used. ### sh_py_run_test The {gh-path}`sh_py_run_test # for example: # bazel run //tools/private/update_deps:update_coverage_deps 7.10.7 ``` ## Updating tool dependencies It's suggested to routinely update the tool versions within our repo. Some of the tools are using requirement files compiled by `uv`, and others use other means. In order to have everything self-documented, we have a special target, `//private:requirements.update`, which uses `rules_multirun` to run all of the requirement-updating scripts in sequence in one go. This can be done once per release as we prepare for releases. (creating-backport-prs)= ## Creating Backport PRs The steps to create a backport PR are: 1. Create an issue for the patch release; use the [patch release template][patch-release-issue]. 2. Create a fork of `rules_python`. 3. Checkout the `release/X.Y` branch. 4. Use `git cherry-pick -x` to cherry pick the desired fixes. 5. Update the release's `CHANGELOG.md` file: * Add a Major.Minor.Patch section if one doesn't exist * Copy the changelog text from `main` to the release's changelog. 6. Send a PR with the backport's changes. * The title should be `backport: PR#N to Major.Minor` * The body must preserve the original PR's number, commit hash, description, and authorship. Use the following format (`git cherry-pick` will use this format): ``` (cherry picked from commit ) ----- Co-authored-by: ``` * If the PR contains multiple backport commits, separate each's description with `-----`. 7. Send a PR to update the `main` branch's `CHANGELOG.md` to reflect the changes done in the patched release. [patch-release-issue]: https://github.com/bazelbuild/rules_python/issues/new?template=patch_release.md