docs: update docs for release process (#193)

Signed-off-by: Shiwei Zhang <shizh@microsoft.com>

.gitignore

@@ -24,3 +24,6 @@ vendor/
 .DS_Store
 /cose-fuzz.zip
 /workdir/
+
+# Editor files
+.vscode/

release-checklist.md

@@ -6,20 +6,18 @@ This document describes the checklist to publish a release via GitHub workflow.
 
 The maintainers may periodically update this checklist based on feedback.
 
-NOTE: Make sure the dependencies in `go.mod` file are expected by the release.
-For example, if there are dependencies on certain version of notation library (notation-go or notation-core-go) or ORAS library (oras-go), make sure that version of library is released first, and the version number is updated accordingly in `go.mod` file.
-After updating go.mod file, run `go mod tidy` to ensure the go.sum file is also updated with any potential changes.
+> [!NOTE]
+> Make sure the dependencies in `go.mod` file are expected by the release.
+> After updating `go.mod` file, run `go mod tidy` to ensure the `go.sum` file is also updated with any potential changes.
 
 ## Release Process
 
-1. Determine a [SemVer2](https://semver.org/)-valid version prefixed with the letter `v` for release.
-For example, `version="v1.0.0-alpha.1"`.
-1. Bump up the `Version` in [internal/version/version.go](internal/version/version.go#L5) and open a PR for the changes.
-1. Wait for the PR merge.
-1. Be on the main branch connected to the actual repository (not a fork) and `git pull`.
-Ensure `git log -1` shows the latest commit on the main branch.
-1. Create a tag `git tag -am $version $version`
-1. `git tag` and ensure the name in the list added looks correct, then push the tag directly to the repository by `git push --follow-tags`.
-1. Wait for the completion of the GitHub action [release-github](https://github.com/veraison/go-cose/blob/main/.github/workflows/ci.yml).
-1. Check the new draft release, revise the release description, and publish the release.
+1. Determine a [SemVer2](https://semver.org/)-valid version prefixed with the letter `v` for release. For example, `v1.0.0-alpha.1`.
+1. Determine the commit to be tagged and released.
+1. Create an issue for voting with title similar to `vote: tag v1.0.0-alpha.1` with the proposed commit.
+1. Wait for the vote pass.
+1. Cut a release branch `release-X.Y` (e.g. `release-1.0`) if it does not exist. The voted commit MUST be the head of the release branch.
+   - To cut a release branch directly on GitHub, navigate to `https://github.com/veraison/go-cose/tree/{commit}` and then follow the [creating a branch](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-and-deleting-branches-within-your-repository#creating-a-branch-using-the-branch-dropdown) doc.
+1. Draft a new release from the release branch by following the [creating a release](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository#creating-a-release) doc. Set release title to the voted version and create a tag in the **Choose a tag** dropdown menu with the voted version as the tag name.
+1. Proofread the draft release, and publish the release.
 1. Announce the release in the community.

release-management.md

@@ -14,31 +14,32 @@ The maintainers may periodically update this policy based on feedback.
 
 ## Release Versioning
 
-Consumers of the go-cose project may build directly from main, or pull from released builds.
-Builds from main must reference the git-commit as the version: `v1.0.0-2300d5c`
+Consumers of the go-cose module may reference `main` directly, or reference released tags.
 
 All go-cose [releases][releases] follow a go-lang flavored derivation (`v*`) of the [semver][sem-ver] format, with optional pre-release labels.
 
-Logical Progression of a release: `v1.0.0-2300d5c` --> `v1.0.0-alpha.1` --> `v1.0.0-alpha.2` --> `v1.0.0-rc.1` --> `v1.0.0`
+Logical Progression of a release: `v1.0.0-alpha.1` --> `v1.0.0-alpha.2` --> `v1.0.0-rc.1` --> `v1.0.0`
 
-A new major or minor release will not have an automated build/release posted until the branch reaches alpha quality.
+A new major or minor release will not have an automated release posted until the branch reaches alpha quality.
 
-- all versions use a preface of `v`
-- `X` is the [Major](#major-releases) version
-- `Y` is the [Minor](#minor-releases) version
-- `Z` is the [Patch](#patch-releases) version
+- All versions use a preface of `v`
+- Given a version `vX.Y.Z`,
+  - `X` is the [Major](#major-releases) version
+  - `Y` is the [Minor](#minor-releases) version
+  - `Z` is the [Patch](#patch-releases) version
 - _Optional_ `-alpha.n` | `-rc.n` [pre-release](#pre-release) version
   - Each incremental alpha or rc build will bump the suffix (`n`) number.
   - It's not expected to have more than 9 alphas or rcs.
 The suffix will be a single digit.
   - If > 9 builds do occur, the format will simply use two digit indicators (`v1.0.0-alpha.10`)
 
-_**Note**: Pre-releases will NOT use the github pre-release flag._
+> [!IMPORTANT]
+> Pre-releases will NOT use the github pre-release flag.
 
 ## Branch Management
 
 To meet the projects stability goals, go-cose does not currently operate with multiple feature branches.
-All active development happens in main.
+All active development happens in `main`.
 For each release, a branch is created for servicing, following the versioning name.
 `v1.0.0-alpha-1` would have an associated [v1.0.0-alpha.1](https://github.com/veraison/go-cose/tree/v1.0.0-alpha.1) branch.
 All version and branch names are lower case.
@@ -76,30 +77,30 @@ Principals of a patch release:
 - No breaking changes.
 - No feature or surface area changes.
 - A "bug fix" that may be a breaking change may require a major release.
-- Applicable fixes, including security fixes, may be cherry-picked from main into the latest supported minor release-X.Y branches.
-- Patch releases are cut from a release-X.Y.Z branch.
+- Applicable fixes, including security fixes, may be cherry-picked from main into the latest supported minor `release-X.Y` branches.
+- Patch releases are cut from a `release-X.Y` branch.
 
 Each patch release will go through one or more `-alpha.n` and `-rc.n` pre-release phases.
 
 ### Pre-Release
 
-As builds of main become stable, and a pending release is planned, a pre-release build will be made.
+As builds of `main` become stable, and a pending release is planned, a pre-release build will be made.
 Pre-releases go through one or more `-alpha.n` releases, followed by one or more incremental `-rc.n` releases.
 
 - **alpha.n:** `X.Y.Z-alpha.n`
   - alpha release, cut from the branch where development occurs.
 To minimize branch management, no additional branches are maintained for each incremental release.
   - Considered an unstable release which should only be used for early development purposes.
   - Released incrementally until no additional issues and prs are made against the release.
-  - Once no triaged issues or pull requests (prs) are scoped to the release, a release candidate (rc) is cut.
+  - Once no triaged issues or pull requests (prs) are scoped to the release, a release candidate (`rc`) is cut.
   - To minimize confusion, and the risk of an alpha being widely deployed, alpha branches and released binaries may be removed at the discretion, and a [two-thirds supermajority][super-majority] vote, of the maintainers.
 Maintainers will create an Issue, and vote upon it for transparency to the decision to remove a release and/or branch.
   - Not [supported](#supported-releases)
 - **rc.n:** `X.Y.Z-rc.n`
   - Released as needed before a final version is released
   - Bugfixes on new features only as reported through usage
-  - An rc is not expected to revert to an alpha release.
-  - Once no triaged issues or prs are scoped to the release, an final version is cut.
+  - An `rc` is not expected to revert to an alpha release.
+  - Once no triaged issues or PRs are scoped to the release, an final version is cut.
   - A release candidate will typically have at least two weeks of bake time, providing the community time to provide feedback.
   - Release candidates are cut from the branch where the work is done.
   - To minimize confusion, and the risk of an rc being widely deployed, rc branches and released binaries may be removed at the discretion, and a [two-thirds supermajority][super-majority] vote, of the maintainers.
@@ -108,9 +109,9 @@ Maintainers will create an Issue, and vote upon it for transparency to the decis
 
 ## Supported Releases
 
-The go-cose maintainers expect to "support" n (current) and n-1 major.minor releases.
+The go-cose maintainers expect to "support" n (current) and `n-1` major.minor releases.
 "Support" means we expect users to be running that version in production.
-For example, when v1.3.0 comes out, v1.1.x will no longer be supported for patches, and the maintainers encourage users to upgrade to a supported version as soon as possible.
+For example, when `v1.3.0` comes out, `v1.1.x` will no longer be supported for patches, and the maintainers encourage users to upgrade to a supported version as soon as possible.
 Support will be provided best effort by the maintainers via GitHub issues and pull requests from the community.
 
 The go-cose maintainers expect users to stay up-to-date with the versions of go-cose release they use in production, but understand that it may take time to upgrade.