Skip to content

Making a Release

John Haddon edited this page Nov 22, 2021 · 6 revisions

This page provides a brief sequential overview of the workflow for releasing a new Gaffer version.

1. Synchronising Branches and Version Numbers

As explained in Branches and Versioning, we develop multiple versions of Gaffer in parallel. This means that we typically release several new versions at the same time, one for each active release branch.

Before releasing, we synchronise the release branches using the procedure defined in Branches and Versioning, but before merging each branch forwards we perform these additional steps :

  • Update the version number in SConstruct.
  • Update the version number in Changes.md. Prior to release we use <milestone>.<major>.x.x to denote the unreleased version, and this is the point we convert to a true version number.

See https://github.com/GafferHQ/gaffer/commit/e93ac5c3df12b873970a9087b3efdbde313e885b for an example of a typical commit performing these steps.

Note : When releasing a new major version for the first time, make a new maintenance branch for it before moving to the next step. The release will be made from this new branch.

git checkout -b <milestoneVersion>.<majorVersion>_maintenance main
git push upstream <milestoneVersion>.<majorVersion>_maintenance

After doing this, bump the major version on main, ready for developing the next major version.

2. Making the Release

Releases are made using the GitHub Releases web interface. Follow the instructions from the GitHub documentation, noting the following :

  • Enter the appropriate tag name for the version you wish to release, e.g. 0.59.9.0. Do not make this tag manually beforehand, but instead let the web UI make it for you. This ensures that the release exists when the build process for the tag kicks in.
  • Make sure you choose the right branch to release from.
  • Enter "Gaffer ..." in the title, substituting the appropriate version number.
  • Copy the appropriate section of Changes.md into the description field.
  • Check "Create a Discussion for this Release".

When making multiple releases, release the lowest version first, so that the latest version takes the top position in the GitHub Releases list.

3. Building the Release

Release builds are made automatically by the GitHub Workflow defined in main.yml. Binaries are uploaded automatically and attached to the release made in step 2. Build progress can be followed at https://github.com/GafferHQ/gaffer/actions.

Note : In a pinch, builds can also be made and uploaded manually using the workflow provided by https://github.com/GafferHQ/build.

4. Updating the Project Board

The Work in Progress project board tracks our current work. When a PR is merged, cards are moved to the "Pending Release" column on the right hand side. After a release, we need to archive the cards that have been included in the release.

image

4. Updating the Website

We host the documentation for the latest version of Gaffer at https://gafferhq.org/documentation, so after each new release we need to update that site. This is performed automatically by a GitHub Action which performs daily checks for new releases and opens a PR to update the site when necessary. This PR needs to be merged by a human to update the site (for example, https://github.com/GafferHQ/documentation/pull/22).

The main website at https://gafferhq.org also needs updating so that the download links point to the latest release. Another GitHub Action takes care of this, creating another PR which needs to be merged by a human (for example, https://github.com/GafferHQ/gafferhq.github.io/pull/80). Note that this PR will not be made until the documentation PR above is merged, because the action checks that the documentation is live before updating the site.