Contributing

Jazzband

This is a Jazzband project. By contributing you agree to abide by the Contributor Code of Conduct and follow the guidelines.

Project Contribution Guidelines

Here are a few additional or emphasized guidelines to follow when contributing to pip-tools:

  • If you need to have a virtualenv outside of tox, it is possible to reuse its configuration to provision it with tox devenv.

  • Always provide tests for your changes and run tox -p all to make sure they are passing the checks locally.

  • Give a clear one-line description in the PR (that the maintainers can add to CHANGELOG afterwards).

  • Wait for the review of at least one other contributor before merging (even if you’re a Jazzband member).

  • Before merging, assign the PR to a milestone for a version to help with the release process.

The only exception to those guidelines is for trivial changes, such as documentation corrections or contributions that do not change pip-tools itself.

Contributions following these guidelines are always welcomed, encouraged and appreciated.

Project Release Process

Releases require approval by a member of the pip-tools-leads team.

Commands given below may assume that your fork is named origin in git remotes and the main repo is named upstream.

This is the current release process:

  • Create a branch for the release. e.g., release/v3.4.0.

  • Use towncrier to update the CHANGELOG, e.g., towncrier build --version v3.4.0.

  • Push the branch to your fork, e.g., git push -u origin release/v3.4.0, and create a pull request.

  • Merge the pull request after the changes are approved.

  • Make sure that the tests/CI still pass.

  • Fetch the latest changes to main locally.

  • Create an unsigned tag with the release version number prefixed with a v, e.g., git tag -a v3.4.0 -m v3.4.0, and push it to upstream.

  • Create a GitHub Release, populated with a copy of the changelog and set to “Create a discussion for this release” in the Announcements category. Some of the markdown will need to be reformatted into GFM. The release title and tag should be the newly created tag.

  • The GitHub Release Workflow will trigger off of the release to publish to PyPI. A member of the pip-tools-leads team must approve the publication step.

  • Once the release to PyPI is confirmed, close the milestone.

  • Publish any release notifications, e.g., pip-tools matrix channel, discuss.python.org, bluesky, mastodon, pypa Discord.

Adding Change Notes with PRs

It is important to maintain a changelog to explain to users what changed between versions.

To avoid merge conflicts, we use Towncrier to maintain our changelog.

Towncrier uses separate files, “news fragments”, for each pull request. On release, those fragments are compiled into the changelog.

You don’t need to install Towncrier to contribute, you just have to follow some simple rules!

  • In your pull request, add a new file into changelog.d/ with a filename formatted as $NUMBER.$CATEGORY.md.

    • The number is the PR number or issue number which your PR addresses.

    • The category is bugfix, feature, deprecation, breaking, doc, packaging, contrib, or misc. The maintainers may use special categories highlights and afterword, but regular contributors don’t generally need to.

    • For example, if your PR fixes bug #404, the change notes should be named changelog.d/404.bugfix.md.

  • If multiple issues are addressed, create a symlink to the change notes with another issue number in the name. Towncrier will automatically merge files into one entry with multiple links.

  • Prefer the simple past or constructions with “now”.

  • Include a byline, -- by {user}`github-username`

You can preview the changelog by running tox run -e build-docs and viewing the changelog in the docs.

Categories

The categories for change notes are defined as follows.

  • bugfix: A fix for something we deemed improper or undesired behavior.

  • feature: A new behavior, such as a new flag or environment variable.

  • deprecation: A declaration of future removals and breaking changes in behavior.

  • breaking: A change in behavior which changes or violates established user expectations (e.g., removing a flag or changing output formatting).

  • doc: Notable updates to the documentation structure or build process.

  • packaging: Changes in how pip-tools itself is packaged and tested which may impact downstreams and redistributors.

  • contrib: Changes to the contributor experience (e.g., running tests, building the docs, or setting up a development environment).

  • misc: Changes that don’t fit any of the other categories.

  • highlights: A prelude to the release notes. Normally filled out by the maintainers with important announcements concerning a pip-tools release. It is rendered before the normal change log categories.

    Important

    The file name must not reference a number but be orphan, starting with a +.

  • afterword: A concluding paragraph after the release notes. May be filled out by the maintainers if they want to include additional free-form notes. It is rendered after the normal change log categories.

    Important

    The file name must not reference a number but be orphan, starting with a +.

Sometimes it’s not clear which category to use for a change. Do your best and a maintainer can discuss this with you during review.

Examples

Example bugfix, 2223.bugfix.md:

Fixed a bug which removed slashes from URLs in `-r` and `-c` in the output
of `pip-compile` -- by {user}`sirosen`.

Example contributor update, 2214.contrib.md:

`pip-tools` now tests on and officially supports `pip` version 25.2
-- by {user}`sirosen`.

Rationale

When making a change to pip-tools, it is important to communicate the differences that end-users will experience in a manner that they can understand.

Details of the change that are primarily of interest only to pip-tools developers may be irrelevant to most users, and if so, then those details can be omitted from the change notes. Then, when the maintainers publish a new release, they’ll automatically use these records to compose a change log for the respective version.

We write change notes in the past tense because this suits the users who will be reading these notes. Combined with others, the notes will be a part of the “news digest” telling the readers what changed in a specific version of pip-tools since the previous version.

This methodology has several benefits, including those covered by the Towncrier Philosophy:

  • Change notes separate the user-facing description of changes from the implementation details. Details go into the git history, but users aren’t expected to care about them.

  • The release engineer may not have been involved in each issue and pull request. Writing the notes early in the process involves the developers in the best position to write good notes.

  • Describing a change can help during code review. The reviewer can better identify which effects of a change were intentional and which were not.