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.

    • 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.

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.