From e5c68f97dfbb7dc2677e891ceea9a8eafe42ddb4 Mon Sep 17 00:00:00 2001 From: Shiwei Zhang Date: Fri, 19 Jul 2024 23:21:40 +0800 Subject: [PATCH] docs: update docs for release process (#193) Signed-off-by: Shiwei Zhang --- .gitignore | 3 +++ .vscode/settings.json | 5 ----- release-checklist.md | 24 +++++++++++------------- release-management.md | 37 +++++++++++++++++++------------------ 4 files changed, 33 insertions(+), 36 deletions(-) delete mode 100644 .vscode/settings.json diff --git a/.gitignore b/.gitignore index 4d0f184..b04f6b0 100644 --- a/.gitignore +++ b/.gitignore @@ -24,3 +24,6 @@ vendor/ .DS_Store /cose-fuzz.zip /workdir/ + +# Editor files +.vscode/ diff --git a/.vscode/settings.json b/.vscode/settings.json deleted file mode 100644 index ad24d8c..0000000 --- a/.vscode/settings.json +++ /dev/null @@ -1,5 +0,0 @@ -{ - "cSpell.words": [ - "supermajority" - ] -} \ No newline at end of file diff --git a/release-checklist.md b/release-checklist.md index abbbf48..fb09d26 100644 --- a/release-checklist.md +++ b/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. diff --git a/release-management.md b/release-management.md index 4d66ce0..6c123bf 100644 --- a/release-management.md +++ b/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,14 +77,14 @@ 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` @@ -91,15 +92,15 @@ Pre-releases go through one or more `-alpha.n` releases, followed by one or more 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.