docs: update release checklist (#387)

Add more details to guide the release process.

Author: lgfa29

CONTRIBUTING.md

@@ -16,14 +16,60 @@ $ make all
 
 ## Releasing a new SDK version
 
-1. Update the [`VERSION`](./VERSION) file with the new version you want to release.
-   - The [`oxide/version.go`](./oxide/version.go) file will be automatically updated when you run
-     `make generate`
-2. Make sure you have run `make all` and pushed any changes. The release will fail if running
-   `make all` causes any changes to the generated code.
-3. Generate the changelog with `make changelog`.
-4. Run `make tag` from your local `main` branch. This is just a command for making a git tag
-   formatted correctly with the version.
-5. Push the tag (the result of `make tag` gives instructions for this) to this repository.
-6. Everything else is triggered from the tag push. Just make sure all the tests pass on the `main`
-   branch before making and pushing a new tag.
+The release process requires you to sign the release tag. Before starting the
+release process, ensure you have Git and GitHub configured with a GPG key to
+sign commits and tags. Refer to
+[GPG commit signature verification](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification#gpg-commit-signature-verification)
+for more information.
+
+- [ ] Create a release branch
+  ```
+  git checkout main
+  git pull origin main
+  git checkout -b release-vX.Y.Z
+  ```
+- [ ] Update the [`VERSION`](./VERSION) and [`VERSION_OMICRON`](./VERSION_OMICRON) files with the new version you want to release.
+- [ ] Generate and lint files.
+  ```
+  make all
+  ```
+- [ ] Ensure the `.changelog/vX.Y.Z.toml` file has the changelog entries for the release and generate changelog.
+  ```
+  make changelog
+  ```
+- [ ] Update the generated file with the release date and associated Oxide API version.
+  ```diff
+  - # vX.Y.Z
+  + # vX.Y.Z (Year/Month/Day)
+  +
+  + Generated from Oxide API version [API VERSION](https://github.com/oxidecomputer/omicron/blob/<OMICRON TAG>/openapi/nexus/nexus-<API VERSION>.json)
+  ```
+- [ ] Commit and push updated files.
+  ```
+  git add -A .
+  git commit -m 'release vX.Y.Z'
+  git push origin release-vX.Y.Z
+  ```
+- [ ] Open a PR to update `main`.
+- [ ] Ensure tests are passing in `main` after merge.
+- [ ] Run `make tag` from your local `main` branch.
+  ```
+  git checkout main
+  git pull origin main
+  make tag
+  ```
+- [ ] Push the tag to this repository.
+  ```
+  git push origin vX.Y.Z
+  ```
+- [ ] Update the GitHub [release](https://github.com/oxidecomputer/oxide.go/releases) description with the release content generated from `make changelog`.
+- [ ] Create and push a release branch from the commit of the release tag.
+  ```
+  git checkout vX.Y.Z
+  git checkout -b X.Y
+  git push origin X.Y
+  ```
+- [ ] Create a new branch to prepare the repository for the next version.
+- [ ] Update the `VERSION` file with the next development version and run `make generate` to update generated files.
+- [ ] Create a new `.changelog/<VERSION>.toml` file with the next development version.
+- [ ] Push changes and open PR.