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:

  1. MAJOR version when we make major UI changes or functionality updates

  2. MINOR version when we make minor UI changes or functionality updates

  3. 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:

  1. MAJOR version when we make breaking changes to the API. This generally means removing an API or fields in an API.

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