# Release Procedure

The release procedure below can be performed by a project member with
"maintainer" or higher privileges on the GitHub repository. It assumes 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`.

## 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.0 minor
   versions.
1. Aim to specifically discuss the release timeline and progress in community
   meetings at least 2 months prior to the scheduled date.
1. Use a GitHub milestone to track issues and PRs that will form part of the
   next release.
1. 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.
1. 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 3.Y.0 minor version of SingularityCE is issued the release process
begins by branching, and then issuing a release candidate for broader testing.

When a new 3.Y.Z patch release is issued, the branch will already be present,
and steps 1-4 should be skipped.

1. From a repository that is up-to-date with main, create a release branch
   e.g. `git checkout upstream/main -b release-3.8`.
1. Push the release branch to GitHub via `git push upstream release-3.8`.
1. Examine the GitHub branch protection rules, to extend them to the new release
   branch if needed.
1. 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 3.Y.0 version.
1. Modify the `README.md`, `INSTALL.md`, `CHANGELOG.md` via PR against the
   release branch, so that they reflect the version to be released.
1. Apply an annotated tag via
   `git tag -a -m "SingularityCE v3.8.0 Release Candidate 1" v3.8.0-rc.1`.
1. Push the tag via `git push upstream v3.8.0-rc.1`.
1. Create a tarball via `mconfig -v && make dist`.
1. Test intallation from the tarball.
1. Compute the sha256sum of the tarball e.g. `sha256sum *.tar.gz > sha256sums`.
1. Create a GitHub release, marked as a 'pre-release', incorporating
   `CHANGELOG.md` information, and attaching the tarball and `sha256sums`.
1. Notify the community about the RC via the Google Group and Slack.

There will often be multiple release candidates issued prior to the final
release of a new 3.Y.0 minor version.

A small 3.Y.Z patch release may not require release candidates where the code
changes are contained, confirmed by the person reporting the bug(s), and well
covered by tests.

## Creating a Final Release

1. Ensure the user and admin documentation is up-to-date for the new version,
   branched, and tagged.
   - [User Docs](https://www.sylabs.io/guides/latest/user-guide/) can be edited
     [here](https://github.com/sylabs/singularity-userdocs)
   - [Admin Docs](https://www.sylabs.io/guides/latest/admin-guide/) can be edited
     [here](https://github.com/sylabs/singularity-admindocs)
1. Ensure the user and admin documentation has been deployed to the sylabs.io
   website.
1. Modify the `README.md`, `INSTALL.md`, `CHANGELOG.md` via PR against the
   release branch, so that they reflect the version to be released.
1. Apply an annotated tag via `git tag -a -m "SingularityCE v3.8.0" v3.8.0`.
1. Push the tag via `git push upstream v3.8.0`.
1. Create a tarball via `mconfig -v && make dist`.
1. Test intallation from the tarball.
1. Compute the sha256sum of the tarball e.g. `sha256sum *.tar.gz > sha256sums`.
1. Create a GitHub release, incorporating `CHANGELOG.md` information, and
   attaching the tarball and `sha256sums`.
1. Notify the community about the RC via the Google Group and Slack.

## After the Release

1. Create and merge a PR from the `release-3.x` branch into `main`, so that
   history from the RC process etc. is captured on `main`.
1. If the release is a new major/minor version, move the prior `release-3.x`
   branch to `vault/release-3.x`.
1. If the release is a new final major/minor version, update the
   `.github/dependabot.yml` configuration to remove the prior stable release
   branch.
1. Start scheduling / setting up milestones etc. to track the next release!
