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>.
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.
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.
There is no cadence for releases: they are made available as necessary.
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.
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
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:
A GitHub Release, with text corresponding to an abbreviated form of the release notes for that cycle, has been created
The following only apply to full releases, or those where the MAJOR or MINOR number is incremented:
A new branch called
stable/MAJOR.MINORhas been created from the tagged commit
Once released, bump the version found in
patchwork/__init__.py once again.
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:
When enough patches have been backported, you should release a new PATCH release.
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:
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.