Project: Krator (App Definition and Development / Application Definition & Image Build)
File: release-checklist.md

If your experience deviates from this document, please document the changes to keep it up-to-date. This guide will guide you (redundancy added for purposes of punnery) on your journey to release a new version of Krator. All releases will be of the form `vX.Y.Z` where `X` is the major version number, `Y` is the minor version number and `Z` is the patch release number. This project strictly follows so following this step is critical. It is important to note that this document assumes that the git remote in your repository that corresponds to <https://github.com/krator-rs/krator> is named `upstream`. If yours is not (for example, if you've chosen to name it `origin` or something similar instead), be sure to adjust the listed snippets for your local environment accordingly. If you are not sure what your upstream remote is named, use a command like `git remote -v` to find out. If you don't have an upstream remote, you can add one easily using the following command: ```console git remote add upstream git@github.com:krator-rs/krator ``` Major releases are for new feature additions and behavioral changes that break backwards compatibility. Minor releases are for new feature additions that do not break backwards compatibility. Patch releases are for bug fixes that do not introduce any new features. There are two versions of the checklist: one for patch releases, and one for major/minor releases. Follow the checklist that best applies below. Follow this checklist if you are cutting a major release (vX.0.0) or a minor release (vX.Y.0): set up your environment increment the version number finalize the release and write the release notes In this checklist, we are going to reference a few environment variables which you will want to set for convenience. For major and minor releases, set the following environment variables, changing the values of `$MAJORRELEASENUMBER`, `$MINORRELEASENUMBER`, and `$RELEASECANDIDATENUMBER` accordingly: ```console export MAJORRELEASENUMBER="0" export MINORRELEASENUMBER="1" export RELEASENAME="v${MAJORRELEASENUMBER}.${MINORRELEASE_NUMBER}.0" ``` Now that we know we are going to cut a major or a minor release, we will need to bump the project's Cargo.toml as well as any crates that have been updated this release. Open a new pull request against Krator, bumping the version fields in Cargo.toml: <https://github.com/krator-rs/krator/blob/main/Cargo.toml#L3> Use the following commands to create the commit: ```console git add . git commit -m "bump version to $RELEASE_NAME" ``` Wait until the pull request has been merged into `main` before proceeding. After the pull request has been merged, create a new tag from upstream's `main` branch. ```console git fetch upstream main git checkout upstream/main git tag --annotate "${RELEASENAME}" --message "Krator release ${RELEASENAME}" ``` Double-check one last time to make sure everything is in order, then finally push the release tag. ```console git push upstream $RELEASE_NAME ``` It is usually more beneficial to the end-user if the release notes are hand-written by a human being/marketing team/dog, so we'll go ahead and write up the release notes. If you're releasing a major/minor release, listing notable user-facing features is usually sufficient. For patch releases, do the same, but make note of the symptoms causing the original issue, who may be affected, and how the patch mitigates the issue. it should look like this: ```markdown Krator vX.Y.Z is a feature release. This release, we focused on <insert focal point here>. Users are encouraged to upgrade for the best experience. TLS bootstrapping support has been added Improved error handling for the Kubernetes API No known breaking changes were introduced this

Needs more cowbell I gotta have more cowbell! ``` Feel free to bring in your own personality into the release notes; it's nice for people to think we're not all robots. :) Double check the URLs are correct. Once finished, go into GitHub and edit the release notes for the tagged release with the notes written here. It is now worth getting other people to take a look at the release notes before the release is published. It is always beneficial as it can be easy to miss something. For pre-v1.0 releases, make sure to check the checkbox that says "This is a pre-release" to notify users that this release is identified as non-production ready. When you are ready to go, hit `publish`, and you're done. Follow this checklist if you are cutting a patch release (vX.Y.Z). The process is largely the same as cutting a major/minor release, but with a few differences. set up your environment increment the version number cherry-pick fixes finalize the release and write the release notes In this checklist, we are going to reference a few environment variables which you will want to set for convenience. For patch releases, set the following environment variables: ```console export MAJORRELEASENUMBER="0" export MINORRELEASENUMBER="1" export PATCHRELEASENUMBER="1" export PREVIOUSPATCHRELEASE_NUMBER="0" export RELEASENAME="v${MAJORRELEASENUMBER}.${MINORRELEASENUMBER}.${PATCHRELEASE_NUMBER}" export PREVIOUSRELEASENAME="v${MAJORRELEASENUMBER}.${MINORRELEASENUMBER}.${PREVIOUSPATCHRELEASE_NUMBER}" export RELEASEBRANCHNAME="release-${MAJORRELEASENUMBER}.${MINORRELEASENUMBER}.${PATCHRELEASENUMBER}" ``` Now that we know we are going to cut a patch release, we will need to bump the project's Cargo.toml as well as any crates that have been updated this release. Open a new pull request against Krator, bumping the version fields in Cargo.toml: <https://github.com/krator-rs/krator/blob/main/Cargo.toml#L3> Use the following commands to create the commit: ```console git add . git commit -m "bump version to $RELEASE_NAME" ``` Wait until the pull request has been merged into `main` before proceeding. After the pull request has been merged, checkout the previous tag from upstream and use it to create a new branch: ```console git fetch upstream --tags git checkout $PREVIOUSRELEASENAME git checkout -b $RELEASEBRANCHNAME ``` Once that's done, make sure to cherry-pick the fixes as well as the version bump from the previous step into this branch: ```console git cherry-pick -x <commit_id> ``` If anyone is available, let others peer-review the branch before continuing to ensure that all the proper fixes have been merged into the release branch. When you're finally happy with the quality of the release branch, you can move on and create the tag. Double-check one last time to make sure everything is in order, then finally push the release tag. ```console git tag --annotate "${RELEASENAME}" --message "Krator release ${RELEASENAME}" git push upstream $RELEASE_NAME ``` It is usually more beneficial to the end-user if the release notes are hand-written by a human being/marketing team/dog, so we'll go ahead and write up the release notes. For patch releases, make note of the symptoms causing the original issue(s), who may be affected, and how the patch(es) mitigate the issue(s). it should look like this: ```markdown Krator vX.Y.Z is a patch release, fixing an issue where <insert diagnosis of issue here>. This patch fixes this issue by <insert remedy here>. Users are encouraged to upgrade for the best experience. No known breaking changes were introduced this release. ``` Double check the URLs are correct. Once finished, go into GitHub and edit the release notes for the tagged release with the notes written here. It is now worth getting other people to take a look at the release notes before the release is published. It is always beneficial as it can be easy to miss something. For pre-v1.0 releases, make sure to check the checkbox that says "This is a