This page describes the "who", "what", and "when" of Pants releases. If you're interested in learning "how" to release, see the Release Process page.
There is one release manager per week, decided via a shared calendar (to volunteer to be added to the calendar, see How to Contribute).
The release manager is responsible for:
- Creating and gathering feedback on release candidates
These release types and responsibilities are described below.
The release manager for a particular week decides whether to cut
stable release. A
rc release from master should happen every week. Stable branches will be created based on the
- Decide whether to create a new
- If it has been approximately three months since the
stablebranch, the release manager should inspect the changes in the current release milestone, and decide whether the changes justify a new
stablerelease (this is intentionally left open for discussion). If a new
stablerelease is justified, it will be made from either a
minorstable branch (described below).
- If a new
stablebranch is not created (because of insufficient time/change to justify the stable vetting process), the release manager must cut a
devrelease from master instead.
- If it has been approximately three months since the previous
- In addition to any
devrelease or newly-created
stablebranches, the release manager should determine whether any existing
stablebranches need new release candidates by looking for changes labelled needs-cherrypick. If there are requests "sufficient" to justify
patchreleases for existing
stablebranches, the release manager should cut release candidates for those branches.
In other words, for a given week: one of either a
rc release will be created from
master. A new
stable branch may be created, and additionally,
patch releases for
stable branches might be created.
dev releases are releases that occur directly from master, without the additional vetting that
is applied to
stable releases. They help to ensure a steady release cadence from master by filling
in the gaps between the (generally more time consuming)
stable release cycles generally happen every few months, provided that there are enough user
facing changes to warrant a new
stable release. For each release candidate for a
five business days should be allocated to bugfixing and testing by pants contributors on a release
candidate announcement thread (described below). If any changes are needed to the stable release
based on feedback a new
rc release will be created from the stable branch.
minor stable branches
The decision to create a
major or a
minor stable branch is based on consensus on
pants-devel@ as to the impact of the changes.
major releases signify large or breaking changes.
minor releases however should be compatible
with the last two
minor releases. In other words if a feature is deprecated in version
you should be able to continue using that feature at least through version
patch stable Releases
In order to allow us to react quickly to bugs,
patch fixes are released for
stable branches as
needed and should always consist of fixes or small backwards-compatible features backported from
master using the needs-cherrypick label. These releases update the patch version number, (ie, from
1.0.y) and should
only include commits that are deemed to be backwards compatible.
Leading up to a
stable release, development work should be done on a branch named with the
n.n.x where n.n are the
minor version numbers and "
x" is a literal
character placeholder for the
patch version. Release candidates of an upcoming
are suffixed with
rcN. For instance: "the
1.1.1rc0 release candidate", and "the
dev releases occur between
stable branches, and are differentiated by a
devN suffix. The pattern
to follow is
N.N are the next
minor branch that will be created
and N is the next sequential number starting from
0. For instance: "the
Note the dot before the
dev0. See https://www.python.org/dev/peps/pep-0440/#public-version-identifiers.
Leading up to the release of
2.0.0the release manager would create a
stablebranch with the literal name "
2.0.x". They would cut release candidates named
2.0.0rc0(and so on), and afterwards, they'd finalize the
2.0.0release in that
2.0.xbranch by tagging the commit with the release version:
v2.0.0. Note the lack of a dot before the
rc0. See https://www.python.org/dev/peps/pep-0440/#public-version-identifiers.
If a release manager had a bugfix from master that they needed to backport to the
stablebranch, they would cherry-pick the commit to the
1.1.xbranch, run a series of release candidates (ie,
1.1.1rc0, etc), and finally tag the validated commit with a new patch version (ie
devreleases were required after having created the
1.0.xbranch, but before having created the
1.1.xbranch, then they would start with
1.1.0.dev0, and continue weekly to
1.1.xbranch had been created.
stable Release Candidates
In order to make a
stable release, the release manager needs to create a release candidate for
contributors to test. Once a release candidate has been created and announced according to the
Release Process, the release manager should allow five business days
for contributors to raise concerns on the release candidate announcement thread. During those five
days the release manager might need to perform multiple release candidates, until finally, when no
more blockers are raised against a particular release candidate, the final version of that release
can be cut.