Document release process and update some just recipes (#3460)

Justfile

@@ -281,12 +281,11 @@ install-deps:
     cd ui/desktop && npm install
     cd documentation && yarn
 
-# ensure the current branch is "main" or error
+ensure-release-branch:
-ensure-main:
     #!/usr/bin/env bash
     branch=$(git rev-parse --abbrev-ref HEAD); \
-    if [ "$branch" != "main" ]; then \
+    if [[ ! "$branch" == release/* ]]; then \
-        echo "Error: You are not on the main branch (current: $branch)"; \
+        echo "Error: You are not on a release branch (current: $branch)"; \
         exit 1; \
     fi
 
@@ -294,7 +293,7 @@ ensure-main:
     git fetch
     # @{u} refers to upstream branch of current branch
     if [ "$(git rev-parse HEAD)" != "$(git rev-parse @{u})" ]; then \
-        echo "Error: Your branch is not up to date with the upstream main branch"; \
+        echo "Error: Your branch is not up to date with the upstream branch"; \
         echo "  ensure your branch is up to date (git pull)"; \
         exit 1; \
     fi
@@ -316,7 +315,7 @@ validate version:
     fi
 
 # set cargo and app versions, must be semver
-release version: ensure-main
+prepare-release version:
     @just validate {{ version }} || exit 1
 
     @git switch -c "release/{{ version }}"
@@ -334,8 +333,8 @@ release version: ensure-main
 get-tag-version:
     @uvx --from=toml-cli toml get --toml-path=Cargo.toml "workspace.package.version"
 
-# create the git tag from Cargo.toml, must be on main
+# create the git tag from Cargo.toml, checking we're on a release branch
-tag: ensure-main
+tag: ensure-release-branch
     git tag v$(just get-tag-version)
 
 # create tag and push to origin (use this when release branch is merged to main)
@@ -344,9 +343,9 @@ tag-push: tag
     git push origin tag v$(just get-tag-version)
 
 # generate release notes from git commits
-release-notes:
+release-notes old:
     #!/usr/bin/env bash
-    git log --pretty=format:"- %s" v$(just get-tag-version)..HEAD
+    git log --pretty=format:"- %s" {{ old }}..v$(just get-tag-version)
 
 ### s = file seperator based on OS
 s := if os() == "windows" { "\\" } else { "/" }

RELEASE.md

@@ -0,0 +1,27 @@
+# Making a Release
+
+You'll generally create one of two release types: a regular feature release (minor version bump) or a bug-fixing patch release (patch version bump). Regular releases start on main, while patch releases start with an existing release tag.
+
+## Regular release from main
+
+1. Check out the main branch.
+2. Pick the new version. Use a new minor version (e.g. if the current latest release is 1.2.3, use 1.3.0). Save it using `export VERSION=<new version>`
+3. Run `just prepare-release $VERSION`. This will create a branch `release/<version>`. Push this branch and open a PR into main. The diff should show version updates to Cargo.toml/package.json and their lock files.
+4. Test this build. When ready to make the release, proceed to the next step.
+5. Tag the release: run `just tag-push` to create the tag and push it. This will start the build process for your new release.
+6. Merge the PR you created in step 2.
+7. Once the release is created on [Github](https://github.com/block/goose/releases), run `just release-notes <prior release>` to generate release notes. Copy these into the release description.
+
+## Patch release
+
+Follow the above steps, but rather than starting on main, start on the release tag you're interested in patching. Increment the patch version instead of minor (e.g. 1.2.3 -> 1.2.4). Bug fixes should be merged to main and then cherry-picked onto this branch.
+
+1. Before proceeding, make sure any fixes you're looking to include in a patch are merged into main, if possible.
+2. Check out the release you're patching using the tag (e.g `git checkout v1.3.0`). Set the version by incrementing the patch version (`export VERSION=1.3.1`).
+3. Run `just prepare-release $VERSION`.
+4. Cherry-pick the relevant fixes from the main branch.
+5. Test this build. When ready to make the release, proceed to the next step.
+6. Tag the release: run `just tag-push` to create the tag and push it. This will start the build process for your new release.
+7. Once the release is created on [Github](https://github.com/block/goose/releases), run `just release-notes <prior release>` to generate release notes. Copy these into the release description.
+
+Note that you won't merge this branch into main.