Release strategy
Our approach to semantic versioning + time-based releases.
Pants follows semantic versioning, along with using regular time-based dev releases. We follow a strict Deprecation policy.
See Community.
Also see Upgrade tips for suggestions on how to effectively upgrade Pants versions.
Stable releases
Stable releases occur roughly every month. They have been vetted through at least one release candidate.
Stable releases are named with the major, minor, and patch version—with no suffix. For example, 2.1.0 or 2.2.1.
Any new patch versions will only include:
- Backward-compatible bug fixes
- Backward-compatible feature backports, as long as they:
- Are requested by users
- Are deemed low-risk and are easy to backport
- Do not introduce new deprecations
Patch versions must have also had at least one release candidate.
We try our best to write bug-free code, but, like everyone, we sometimes make mistakes.
If you encounter a bug, please gently let us know by opening a GitHub issue or messaging us on Slack. See Community.
Release candidates
rc releases are on track to being stable, but may still have some issues.
Release candidates are named with the major, minor, and patch version, and end in rc and a number. For example, 2.1.0rc0 or 2.1.0rc1.
Release candidates should only contain bug fixes; they should generally not include new features or new deprecations. (Exception for rc0, which can include the same changes as a normal dev release.)
We greatly appreciate when users test out release candidates. While we do our best to have comprehensive CI—and we "dogfood" release candidates—we are not able to test all the ways Pants is used in the wild.
If you encounter a bug, please gently let us know by opening a GitHub issue or messaging us on Slack. See Community.
A stable release cannot be created until a minimum of 5 business days from the first rc0 release. Typically, during this time, there will be multiple release candidates to fix any issues discovered.
A stable release can be created two business days after the most recent release candidate if there are no more blockers.
Dev releases
dev releases are weekly releases that occur directly from the main branch, without the additional vetting that is applied to stable releases and release candidates. Usually, these are released on Friday or Monday.
Dev releases help to ensure a steady release cadence from main by filling in the gaps between the more time consuming stable releases.
Dev releases are named with the major, minor, and patch version, and end in .dev and a number. For example, 2.1.0.dev0 or 2.1.0.dev1.
Dev releases can include any changes, so long as they comply with the Deprecation policy.
Usually, we release 3-4 dev releases before switching to the first release candidate rc0. This means we usually release dev0, dev1, dev2, sometimes dev3, and then rc0.
We try to limit the number of changes in each stable release to make it easier for users to upgrade. If the dev releases have been particularly disruptive, such as making major deprecations, we may start a release candidate sooner, such as after dev1.