Release Process
Versioning
There are two types of versioning in play in Patchwork: the version for Patchwork itself (i.e. the code or core) and the version for the REST API <../api/rest>.
Patchwork Code
Since version 1.0, Patchwork has implemented a version of Semantic Versioning . To summarise, releases take the format MAJOR.MINOR.PATCH (or just MAJOR.MINOR). We increment:
MAJOR version when we make major UI changes or functionality updates
MINOR version when we make minor UI changes or functionality updates
PATCH version when we make make bug fixes, dependency updates etc.
In Git, each release will have a tag indicating the version number. In addition, each release series has it’s own branch called stable/MAJOR.MINOR to allow backporting of bugfixes or security updates to older versions.
REST API
The REST API also uses a variant of Semantic Versioning. To summarise, API versions take the format MAJOR.MINOR. We increment:
MAJOR version when we make breaking changes to the API. This generally means removing an API or fields in an API.
MINOR version when we add functionality in a backwards-compatible manner. This generally means adding new fields and endpoint.
These version numbers are exposed via the API and it’s possible to request a specific version in the URL. Refer to the API Guide <../api/rest> for more information.
Release Cycle
There is no cadence for releases: they are made available as necessary.
Supported Versions
Typically all development should occur on main
. While we will backport
bugfixes and security updates, we will not backport any new features. This is
to ensure stability for users of these versions of Patchwork.
Release Checklist
The follow steps apply to all releases:
Documentation has been updated with latest release version
Documentation references latest supported version of Django
‘alpha’ tag has been removed from the version in in
version.txt
Commit has been tagged with an annotated tag. The tag should take the form v[MAJOR].[MINOR].[PATCH], e.g. v2.0.1. The message should read:
Version [MAJOR].[MINOR].[PATCH]
A GitHub Release, with text corresponding to an abbreviated form of the release notes for that cycle, has been created
An email describing the release and top-level overview of the changes has been sent to the mailing list. Refer to the emails for Patchwork v2.0.0 and Patchwork v2.0.1 for examples.
The following only apply to full releases, or those where the MAJOR or MINOR number is incremented:
A new branch called
stable/MAJOR.MINOR
has been created from the tagged commit
Once released, bump the version found in version.txt
once again.
Backporting
We will occasionally backport bugfixes and security updates. When backporting a
patch, said patch should first be merged into main
. Once merged, you can
backport by cherry-picking commits, using the -x
flag for posterity:
$ git cherry-pick -x <main_commit>
There may be some conflicts; resolve these, uncommenting the Conflicts line when committing:
Conflicts
patchwork/bin/pwclient
When enough patches have been backported, you should release a new PATCH release.
Backport criteria
We consider bug fixes and security updates to the Patchwork code itself valid for backporting, along with fixes to documentation and developer tooling. We do not, however, consider the following backportable:
- Features
Backporting features is complicated and introduces instability in what is supposed to be stable release. If new features are required, users should update their Patchwork version.
- API changes
Except for bug fixes that resolve 5xx-class errors or fix security issues. This also applies to API versions.
- Requirement changes
Requirements on a stable branch are provided as a “snapshot in time” and, as with features, should not change so as to prevent instability being introduced in a stable branch. In addition, stable requirements are not a mechanism to alert users to security vulnerabilities and should not be considered as such. Users of stable branches should either rely on distro-provided dependencies, which generally maintain a snapshot-in-time fork of packages and selectively backport fixes to them, or manage dependencies manually. In cases, where using a distro-provided package necessitates minor changes to the Patchwork code, these can be discussed on a case-by-case basis.