documentation: add release documentation

Adding information about how to release claircore from main and from a release branch. Signed-off-by: crozzy <[email protected]>
quay · Jan 10, 2025 · 9f759aa · 9f759aa
1 parent 6bbe356
commit 9f759aa
Show file tree

Hide file tree

Showing 3 changed files with 48 additions and 0 deletions.
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
@@ -39,5 +39,6 @@
   - [Local Development](./contributor/local-dev.md)
   - [Logging](./contributor/logging.md)
   - [Misc](./contributor/misc.md)
+  - [Releases](./contributor/releases.md)
   - [Tests](./contributor/tests.md)
   - [Go Version](./contributor/go_version.md)
diff --git a/docs/contributor.md b/docs/contributor.md
@@ -2,7 +2,9 @@
 
 These topics cover helpful tips for contributing to Claircore.
 
+- [Changelog](./contributor/changelog.md)
 - [Local Development](./contributor/local-dev.md)
 - [Logging](./contributor/logging.md)
 - [Misc](./contributor/misc.md)
+- [Releases](./contributor/releases.md)
 - [Tests](./contributor/tests.md)
diff --git a/docs/contributor/releases.md b/docs/contributor/releases.md
@@ -0,0 +1,45 @@
+# Releases
+
+Claircore releases are cut when they are needed, as judged by the maintainers.
+
+Releases are made from the `main` branch.
+On rare occasions when a fix is time-sensitive, it is possible to create a release branch and make a release from it.
+
+## Process
+
+> **_NOTE:_** Ensure changelog entries have been created for the relevant commits.
+> (see [Changelog documentation](./changelog.md))
+
+### From main
+
+```sh
+NEW_VERSION=v0.999.999
+.github/scripts/prepare-release -b main -r upstream "$NEW_VERSION"
+```
+
+Follow the `prepare-release` command's instructions to merge changelog updates and release the tag.
+
+### From release branch
+
+First create the relevant release branch (e.g if you are releasing `v1.6.1` create `release-1.6` from the
+previous tag (in this case `v1.6.0`)). Then backport any commits and push up the release branch.
+
+```sh
+LAST_MINOR=v0.999.0
+BRANCH=release-${LAST_MINOR%.*} # e.g. release-v0.999
+git branch $BRANCH $LAST_MINOR
+TO_BACKPORT=beefc0ffee # Use the commit digest of the original commit
+git cherry-pick -x $TO_BACKPORT
+git push upstream $BRANCH
+```
+
+Finally, prepare the release specifying the release branch.
+
+```sh
+LAST_MINOR=v0.999.0
+NEW_VERSION=v0.999.1
+BRANCH=release-${LAST_MINOR%.*} # e.g. release-v0.999
+.github/scripts/prepare-release -b $BRANCH -r upstream $NEW_VERSION
+```
+
+Follow the `prepare-release` command's instructions to merge changelog updates and release the tag.