Skip to content

RELEASE_PROCEDURE.md

Latest commit

 

History

History
160 lines (137 loc) · 8.08 KB

RELEASE_PROCEDURE.md

File metadata and controls

160 lines (137 loc) · 8.08 KB
Raw

Release Procedures

The release procedures below can be performed by a project member with "maintainer" or higher privileges on the GitHub repository. They assume that you will be working in an up-to-date local clone of the GitHub repository, where the upstream remote points to github.com/sylabs/singularity.

There are two different release procedures:

  • A new patch release, e.g. releasing 3.11.3 when the current release is 3.11.2, follows a short procedure that can be completed within a day.
  • A new major or minor version, e.g. releasing 3.12.0 when the current release is 3.11.1, requires a longer procedure that takes a minimum of 2 weeks. This includes a release candidate period, creation of a new release branch, new documentation branches etc.

Patch Releases

A patch release is made from an existing release-XXX branch, to provide fixes for the current stable major.minor version of SingularityCE.

Prior to Patch Release

  1. Set a target date for the patch release.
  2. Use a GitHub milestone to track issues and PRs that will form part of the patch release.
  3. Cherry pick fixes from the main branch onto the release-XXX branch.
  4. Ensure that the CHANGELOG.md is kept up-to-date on the release-XXX branch, with all relevant changes listed under a "Changes Since Last Release" section.
  5. Monitor and merge dependabot updates, such that a release is made with as up-to-date versions of dependencies as possible. This lessens the burden in addressing patch release fixes that require dependency updates, as we use several dependencies that move quickly.
  6. Identify and manually test any changes that are not exercised by the CI pipeline. E.g. cgroups v1 code.

Creating the Patch Release

  1. Check the version of Go installed in the CI environment from .circleci/config.yml. Ensure that it is the latest release, as it will be used to build our release packages. Update if necessary via a PR against the release branch.
  2. Modify the README.md, INSTALL.md, CHANGELOG.md via PR against the release branch, so that they reflect the version to be released. Also modify Go version mentioned in INSTALL.md, if that has changed since last release.
  3. After all PRs are merged, apply an annotated tag to the HEAD of the release branch via git tag -a -m "SingularityCE v3.11.3" v3.11.3.
  4. Push the tag to the GitHub repository via git push upstream v3.11.3.
  5. Download the rpm and deb packages, which are generated as CI job artifacts, from the CircleCI workflow for the tag.
  6. Create a tarball locally, via git clean -fdx && ./mconfig -v && make -C builddir dist.
  7. Test installation locally from the tarball.
  8. Create a GitHub release, using the previous release as a guide and incorporating CHANGELOG.md information. Attach the tarball, rpms, and debs to it.
  9. Notify the community about the release via the Google Group and Slack.

After the Patch Release

  1. Create and merge a PR from the release-XXX branch into main, so that the changelog is synchronized etc.

Major / Minor Releases

A Major release (e.g. 3.11 -> 4.0), or minor release (e.g. 3.11 -> 3.12) requires a minimum of two weeks to complete. This allows time for feedback on at least one release candidate to be received from the user community.

Prior to Release

  1. Set a target date for the release candidate (if required) and release. Generally 2 weeks from RC -> release is appropriate for new 3.X minor versions. A major release may need a longer RC period.
  2. Aim to specifically discuss the release timeline and progress in community meetings at least 2 months prior to the scheduled date.
  3. Use a GitHub milestone to track issues and PRs that will form part of the next release.
  4. Ensure that the CHANGELOG.md is kept up-to-date on the main branch, with all relevant changes listed under a "Changes Since Last Release" section.
  5. Monitor and merge dependabot updates, such that a release is made with as up-to-date versions of dependencies as possible. This lessens the burden in addressing patch release fixes that require dependency updates, as we use several dependencies that move quickly.

Creating the Release Branch and Release Candidate

When a new major or minor version of SingularityCE is issued the release process begins by branching, and then issuing, a release candidate for broader testing.

  1. From a repository that is up-to-date with the main branch, create a release branch e.g. git checkout upstream/main -b release-3.12.
  2. Push the release branch to the GitHub repository via git push upstream release-3.12.
  3. Examine the GitHub branch protection rules, to extend them to the new release branch if needed.
  4. Update the .github/dependabot.yml configuration so that dependabot is tracking the new stable release branch. Do not remove the previous stable release branch from the configuration yet, as it should be monitored until the final release of a new version.
  5. Check the version of Go installed in the CI environment from .circleci/config.yml. Ensure that it is the latest release, as it will be used to build our release packages. Update if necessary via a PR against the release branch.
  6. Modify the README.md, INSTALL.md, CHANGELOG.md via PR against the release branch, so that they reflect the release candidate version to be issued. Also modify Go version mentioned in INSTALL.md, if that has changed since last release.
  7. Apply an annotated tag via git tag -a -m "SingularityCE v3.11.0 Release Candidate 1" v3.11.0-rc.1.
  8. Push the tag via git push upstream v3.11.0-rc.1.
  9. Download the rpm and deb packages, which are generated as CI job artifacts, from the CircleCI workflow for the tag.
  10. Create a tarball locally, via git clean -fdx && ./mconfig -v && make -C builddir dist.
  11. Test installation locally from the tarball.
  12. Create a GitHub pre-release, using the previous release as a guide and incorporating CHANGELOG.md information. Make sure it is clear to users that the release candidate is not for production use. Attach the tarball, rpms, and debs to it.
  13. Notify the community about the release candidate via the Google Group and Slack.

There will often be multiple release candidates issued prior to the final release of a new major or minor version. Each new RC follows step 5 and above.

Creating a Final Major / Minor Release

  1. Ensure the user and admin documentation is up-to-date for the new version, has been branched, and tagged.
  2. Ensure the user and admin documentation has been deployed to the sylabs.io website.
  3. Modify the README.md, INSTALL.md, CHANGELOG.md via PR against the release branch, so that they reflect the version to be released. Also modify Go version mentioned in INSTALL.md, if that has changed since last release.
  4. Apply an annotated tag via git tag -a -m "SingularityCE v3.12.0" v3.12.0.
  5. Push the tag via git push upstream v3.12.0.
  6. Download the rpm and deb packages, which are generated as CI job artifacts, from the CircleCI workflow for the tag.
  7. Create a tarball locally, via git clean -fdx && ./mconfig -v && make -C builddir dist.
  8. Test installation locally from the tarball.
  9. Create a GitHub release, using the previous release as a guide and incorporating CHANGELOG.md information. Attach the tarball, rpms, and debs to it.
  10. Notify the community about the release candidate via the Google Group and Slack.

After the Release

  1. Create and merge a PR from the release-XXX branch into main, so that history from the RC process etc. is captured on main.
  2. Move the prior release-XXX branch to vault/release-XXX.
  3. Update the .github/dependabot.yml configuration to remove the prior stable release branch.
  4. Start scheduling / setting up milestones etc. to track the next release!