Skip to content

Latest commit

 

History

History
153 lines (130 loc) · 7.3 KB

RELEASE_PROCEDURE.md

File metadata and controls

153 lines (130 loc) · 7.3 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/apptainer/apptainer.

There are two different release procedures:

  • A new patch release, e.g. releasing 1.1.9 when the current release is 1.1.8, follows a short procedure that can be completed within a day.
  • A new major or minor version, e.g. releasing 1.2.0 when the current release is 1.1.8, 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 Apptainer.

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. Identify and manually test any changes that are not exercised by the CI pipeline. E.g. cgroups v1 code.

Creating the Patch Release

  1. Modify the INSTALL.md and 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.
  2. After all PRs are merged, apply an annotated tag to the HEAD of the release branch via git tag -a -m "Apptainer v1.1.9" v1.1.9.
  3. Push the tag to the GitHub repository via git push upstream v1.1.9.
  4. Create a GitHub release, using the previous release as a guide and incorporating CHANGELOG.md information.
  5. 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. 1.1 -> 2.0), or minor release (e.g. 1.1 -> 1.2) 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 1.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 Apptainer 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-1.2.
  2. Push the release branch to the GitHub repository via git push upstream release-1.2.
  3. Examine the GitHub branch protection rules, to extend them to the new release branch if needed. Also examine .github/dependabot.yml to see if the new branch should be added there.
  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. Modify the INSTALL.md and 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.
  6. Apply an annotated tag via git tag -a -m "Apptainer v1.2.0 Release Candidate 1" v1.2.0-rc.1.
  7. Push the tag via git push upstream v1.2.0-rc.1.
  8. Create a GitHub pre-release, using the previous release as a guide and incorporating CHANGELOG.md information. Make sure it is clear to use
  9. Notify the community about the release candidate via the announce Google Group and Slack #general channel.

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 has been deployed to the apptainer.org website.
  2. Modify the INSTALL.md and CHANGELOG.md via PR against the release-1.Y 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. Apply an annotated tag via git tag -a -m "Apptainer v1.2.0" v1.2.0.
  4. Push the tag via git push upstream v1.2.0.
  5. Create a GitHub release, using the previous release as a guide and incorporating CHANGELOG.md information. Attach the tarball, rpms, debs, and sha256sums to it.
  6. Notify the community about the release candidate via the announce Google Group and the Slack #general channel.
  7. Ensure the user and admin documentation is up-to-date for the new version, has been branched, and tagged.
    • User Docs can be edited here. Be sure that the apptainer_source submodule is up to date by doing the following commands followed by making an update with a pull request:
      • git submodule deinit -f .
      • git submodule update --init
      • cd apptainer_source
      • git fetch
      • git checkout v1.2.0
      • cd ..
      • git add apptainer_source
    • Admin Docs can be edited here
    • Look in replacements.py in both the User Docs and Admin Docs for any needed updates to the variable_replacements and also update version in conf.py.
    • If a new branch was created, add it to the docsVersion list in the web page. The latest symlinks in static/docs/user and static/docs/admin should get automatically updated.
    • Make a web announcement of the new release at src/posts.

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. Update the .github/dependabot.yml configuration to remove the prior stable release branch.
  3. Start scheduling / setting up milestones etc. to track the next release!