From 892958155fa50fe76bf85823e49f04a20a855f7e Mon Sep 17 00:00:00 2001 From: steve lasker Date: Tue, 9 Jul 2024 17:26:04 -0700 Subject: [PATCH 1/6] Document the release process Signed-off-by: steve lasker --- .vscode/settings.json | 5 ++ release-checklist.md | 23 +++++++ release-management.md | 148 ++++++++++++++++++++++++++++++++++++++++++ reports/README.md | 6 +- 4 files changed, 179 insertions(+), 3 deletions(-) create mode 100644 .vscode/settings.json create mode 100644 release-checklist.md create mode 100644 release-management.md diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000..ad24d8c --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,5 @@ +{ + "cSpell.words": [ + "supermajority" + ] +} \ No newline at end of file diff --git a/release-checklist.md b/release-checklist.md new file mode 100644 index 0000000..40f0ceb --- /dev/null +++ b/release-checklist.md @@ -0,0 +1,23 @@ +# Release Checklist + +## Overview + +This document describes the checklist to publish a release via GitHub workflow. + +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. + +## 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. Announce the release in the community. diff --git a/release-management.md b/release-management.md new file mode 100644 index 0000000..a4baf79 --- /dev/null +++ b/release-management.md @@ -0,0 +1,148 @@ +# go-cose Release Management + +## Overview + +This document describes [go-cose][go-cose] project release management, which includes release criteria, versioning, supported releases, and supported upgrades. + +The go-cose project maintainers strive to provide a stable go-lang implementation for interacting with [COSE][ietf-cose] constructs. +Stable implies appropriate and measured changes to the library assuring consumers have the necessary functionality to interact with COSE objects. +If you or your project require added functionality, or bug fixes, please open an issue or create a pull request. +The project welcomes all contributions from adding functionality, implementing testing to security reviews. +Please see [here](https://github.com/veraison#contributing) for how to contribute. + +## 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` + +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` + +A new major or minor release will not have an automated build/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 +- _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._ + +## Branch Management + +To meet the projects stability goals, go-cose does not currently operate with multiple feature branches. +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. + +### Major Releases + +The go-cose project will issue major releases when substantial functionality has changed, including: + +- New capabilities consumers may want to opt-into, rather than automatically get as a result of getting the latest minor release or patch. +New and unexpected capabilities _can_ be an attack vector. +Making explicit opt-in decisions to upgrade, or possibly downgrade should be the choice of a project consuming go-cose. +- Breaking Changes, where projects should make an implicit decision to upgrade, and adjust for breaking changes. + +Each major release will go through one or more `-alpha.n` and `-rc.n` pre-release phases. + +### Minor Releases + +The go-cose project will issue minor releases when incremental improvements, or bug fixes are added to existing functionality in a [Major Release](#major-releases). +Minor releases will increment the minor field within the [semver][sem-ver] format. + +Each minor release will go through one or more `-alpha.n` and `-rc.n` pre-release phases. + +### Patch Releases + +Patch Releases include bug and security fixes. +Patches will branch from the released branch being patched. +Fixes completed in main may be ported to a patch release if the maintainers believe the effort is justified by requests from the go-cose community. +If a bug fix requires new incremental, non-breaking change functionality, a new minor release may be issued. + +Principals of a patch release: + +- Should be a "safe bet" to upgrade to. +- 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. + +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. +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 prs are scoped to the release, an 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 +- **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. + - A release candidate will typically have at least two weeks of bake time, providing the community time to provide feedback. + - Release candidate 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. +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 + +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. +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. +We expect users to be running approximately the latest patch release of a given minor release and encourage users to upgrade as soon as possible. + +While pre-releases may be deleted at the discretion of the maintainers, all Major, Minor and Patch releases should be maintained. +Only in extreme circumstances, as agreed upon by a [two-thirds supermajority][super-majority] of the maintainers, shall a release be removed. + +Applicable fixes, including security fixes, may be cherry-picked into the release branch, depending on severity and feasibility. +Patch releases are cut from that branch as needed. + +## Security Reviews + +The go-cose library is an sdk around underlying crypto libraries, tailored to COSE scenarios. +The go-cose library does not implement cryptographic functionality, reducing the potential risk. +To assure go-cose had the proper baseline, two [security reviews](./reports) were conducted prior to the [v1.0.0](https://github.com/veraison/go-cose/releases/tag/v1.0.0) release + +For each release, new security reviews are evaluated by the maintainers as required or optional. +The go-cose project welcomes additional security reviews. +See [SECURITY.md](./SECURITY.md) for more information. + +## Glossary of Terms + +- **X.Y.Z** refers to the version (based on git tag) of go-cose that is released. +This is the version of the go-cose binary. +- **Breaking changes** refer to schema changes, flag changes, and behavior changes of go-cose that may require existing content to be upgraded and may also introduce changes that could break backward compatibility. +- **Milestone** GitHub milestones are used by maintainers to manage each release. +PRs and Issues for each release should be created as part of a corresponding milestone. +- **Patch releases** refer to applicable fixes, including security fixes, may be backported to support releases, depending on severity and feasibility. + +## Attribution + +This document builds on the ideas and implementations of release processes from the [notation](https://github.com/notaryproject/notation) project. + +[go-cose]: https://github.com/veraison/go-cose +[ietf-cose]: https://datatracker.ietf.org/group/cose/about/ +[sem-ver]: https://semver.org +[releases]: https://github.com/veraison/go-cose/releases +[super-majority]: https://en.wikipedia.org/wiki/Supermajority#Two-thirds_vote diff --git a/reports/README.md b/reports/README.md index d624698..7dc67f2 100644 --- a/reports/README.md +++ b/reports/README.md @@ -1,10 +1,10 @@ # Security Reports -This folder contains all the security review reports for the go-cose library. +This folder contains all the security review reports for the go-cose library. ## List of Security Reports | Review Date | Name of Security Review | Report Location | -|:------------|:--------------------------------------| ------------------------------- +|:------------|:--------------------------------------| -------------------------------| | May 16, 2022 | NCC Group go-cose Security Assessment | [NCC Report](./NCC_Microsoft-go-cose-Report_2022-05-26_v1.0.pdf) | -| July 26, 2022 | Trail of Bits go-cose Security Assessment | [Trail of Bits Report](./Trail-of-Bits_Microsoft-go-cose-Report_2022-07-26_v1.0.pdf) | \ No newline at end of file +| July 26, 2022 | Trail of Bits go-cose Security Assessment | [Trail of Bits Report](./Trail-of-Bits_Microsoft-go-cose-Report_2022-07-26_v1.0.pdf) | From a483ffa91c6b2226916f9e6af5b111e94a4a6a09 Mon Sep 17 00:00:00 2001 From: Steve Lasker Date: Thu, 11 Jul 2024 08:54:36 -0700 Subject: [PATCH 2/6] Update release-management.md Signed-off-by: steve lasker Co-authored-by: Orie Steele --- release-management.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/release-management.md b/release-management.md index a4baf79..e25d9e9 100644 --- a/release-management.md +++ b/release-management.md @@ -87,7 +87,7 @@ 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 prs are scoped to the release, an 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 From 7716b966beb04d7a1c8500f5aa8f77376c60a3f9 Mon Sep 17 00:00:00 2001 From: steve lasker Date: Thu, 11 Jul 2024 09:29:42 -0700 Subject: [PATCH 3/6] PR feedback Signed-off-by: steve lasker --- release-management.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/release-management.md b/release-management.md index a4baf79..1da14dc 100644 --- a/release-management.md +++ b/release-management.md @@ -90,17 +90,17 @@ To minimize branch management, no additional branches are maintained for each in - Once no triaged issues or prs are scoped to the release, an 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 + - 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. - A release candidate will typically have at least two weeks of bake time, providing the community time to provide feedback. - - Release candidate are cut from the branch where the work is done. + - 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. Maintainers will create an Issue, and vote upon it for transparency to the decision to remove a release and/or branch. - - Not supported + - Not [supported](#supported-releases) ## Supported Releases From db639095655966c36e3771ba1fbd0c57dd915bd2 Mon Sep 17 00:00:00 2001 From: Steve Lasker Date: Thu, 11 Jul 2024 09:35:23 -0700 Subject: [PATCH 4/6] Update release-management.md Signed-off-by: steve lasker Co-authored-by: Yogesh Deshpande --- release-management.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/release-management.md b/release-management.md index 6094f8e..1f99f91 100644 --- a/release-management.md +++ b/release-management.md @@ -54,7 +54,7 @@ Each major release will go through one or more `-alpha.n` and `-rc.n` pre-releas ### Minor Releases -The go-cose project will issue minor releases when incremental improvements, or bug fixes are added to existing functionality in a [Major Release](#major-releases). +The go-cose project will issue minor releases when incremental improvements, or bug fixes are added to existing functionality. Minor releases will increment the minor field within the [semver][sem-ver] format. Each minor release will go through one or more `-alpha.n` and `-rc.n` pre-release phases. From ab602d2b23cfe086d6a8dea8123f6aab00bf5a80 Mon Sep 17 00:00:00 2001 From: steve lasker Date: Thu, 11 Jul 2024 09:44:04 -0700 Subject: [PATCH 5/6] PR feedback Signed-off-by: steve lasker --- release-management.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/release-management.md b/release-management.md index 6094f8e..b0338b0 100644 --- a/release-management.md +++ b/release-management.md @@ -7,7 +7,7 @@ This document describes [go-cose][go-cose] project release management, which inc The go-cose project maintainers strive to provide a stable go-lang implementation for interacting with [COSE][ietf-cose] constructs. Stable implies appropriate and measured changes to the library assuring consumers have the necessary functionality to interact with COSE objects. If you or your project require added functionality, or bug fixes, please open an issue or create a pull request. -The project welcomes all contributions from adding functionality, implementing testing to security reviews. +The project welcomes all contributions from adding functionality, implementing testing, security reviews to the release management. Please see [here](https://github.com/veraison#contributing) for how to contribute. ## Release Versioning @@ -43,12 +43,14 @@ All version and branch names are lower case. ### Major Releases -The go-cose project will issue major releases when substantial functionality has changed, including: +As a best practice, consumers should opt-into new capabilities through major releases. +The go-cose project will not add new functionality to patches or minor releases as this could create a new surface area that may be exploited. +Consumers should make explicit opt-in decisions to upgrade, or possibly downgrade if necessary due to unexpected breaking changes. -- New capabilities consumers may want to opt-into, rather than automatically get as a result of getting the latest minor release or patch. -New and unexpected capabilities _can_ be an attack vector. -Making explicit opt-in decisions to upgrade, or possibly downgrade should be the choice of a project consuming go-cose. -- Breaking Changes, where projects should make an implicit decision to upgrade, and adjust for breaking changes. +The go-cose project will issue major releases when: + +- Functionality has changed +- Breaking changes are required Each major release will go through one or more `-alpha.n` and `-rc.n` pre-release phases. From d8609dd24fef0a7bdae45e46ce99637bd021fced Mon Sep 17 00:00:00 2001 From: steve lasker Date: Thu, 11 Jul 2024 10:07:05 -0700 Subject: [PATCH 6/6] PR feedback Signed-off-by: steve lasker --- release-checklist.md | 2 ++ release-management.md | 2 ++ 2 files changed, 4 insertions(+) diff --git a/release-checklist.md b/release-checklist.md index 40f0ceb..abbbf48 100644 --- a/release-checklist.md +++ b/release-checklist.md @@ -4,6 +4,8 @@ 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. diff --git a/release-management.md b/release-management.md index cb580ea..4d66ce0 100644 --- a/release-management.md +++ b/release-management.md @@ -10,6 +10,8 @@ If you or your project require added functionality, or bug fixes, please open an The project welcomes all contributions from adding functionality, implementing testing, security reviews to the release management. Please see [here](https://github.com/veraison#contributing) for how to contribute. +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.