|
| 1 | +# go-cose Release Management |
| 2 | + |
| 3 | +## Overview |
| 4 | + |
| 5 | +This document describes [go-cose][go-cose] project release management, which includes release criteria, versioning, supported releases, and supported upgrades. |
| 6 | + |
| 7 | +The go-cose project maintainers strive to provide a stable go-lang implementation for interacting with [COSE][ietf-cose] constructs. |
| 8 | +Stable implies appropriate and measured changes to the library assuring consumers have the necessary functionality to interact with COSE objects. |
| 9 | +If you or your project require added functionality, or bug fixes, please open an issue or create a pull request. |
| 10 | +The project welcomes all contributions from adding functionality, implementing testing, security reviews to the release management. |
| 11 | +Please see [here](https://github.com/veraison#contributing) for how to contribute. |
| 12 | + |
| 13 | +The maintainers may periodically update this policy based on feedback. |
| 14 | + |
| 15 | +## Release Versioning |
| 16 | + |
| 17 | +Consumers of the go-cose project may build directly from main, or pull from released builds. |
| 18 | +Builds from main must reference the git-commit as the version: `v1.0.0-2300d5c` |
| 19 | + |
| 20 | +All go-cose [releases][releases] follow a go-lang flavored derivation (`v*`) of the [semver][sem-ver] format, with optional pre-release labels. |
| 21 | + |
| 22 | +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` |
| 23 | + |
| 24 | +A new major or minor release will not have an automated build/release posted until the branch reaches alpha quality. |
| 25 | + |
| 26 | +- all versions use a preface of `v` |
| 27 | +- `X` is the [Major](#major-releases) version |
| 28 | +- `Y` is the [Minor](#minor-releases) version |
| 29 | +- `Z` is the [Patch](#patch-releases) version |
| 30 | +- _Optional_ `-alpha.n` | `-rc.n` [pre-release](#pre-release) version |
| 31 | + - Each incremental alpha or rc build will bump the suffix (`n`) number. |
| 32 | + - It's not expected to have more than 9 alphas or rcs. |
| 33 | +The suffix will be a single digit. |
| 34 | + - If > 9 builds do occur, the format will simply use two digit indicators (`v1.0.0-alpha.10`) |
| 35 | + |
| 36 | +_**Note**: Pre-releases will NOT use the github pre-release flag._ |
| 37 | + |
| 38 | +## Branch Management |
| 39 | + |
| 40 | +To meet the projects stability goals, go-cose does not currently operate with multiple feature branches. |
| 41 | +All active development happens in main. |
| 42 | +For each release, a branch is created for servicing, following the versioning name. |
| 43 | +`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. |
| 44 | +All version and branch names are lower case. |
| 45 | + |
| 46 | +### Major Releases |
| 47 | + |
| 48 | +As a best practice, consumers should opt-into new capabilities through major releases. |
| 49 | +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. |
| 50 | +Consumers should make explicit opt-in decisions to upgrade, or possibly downgrade if necessary due to unexpected breaking changes. |
| 51 | + |
| 52 | +The go-cose project will issue major releases when: |
| 53 | + |
| 54 | +- Functionality has changed |
| 55 | +- Breaking changes are required |
| 56 | + |
| 57 | +Each major release will go through one or more `-alpha.n` and `-rc.n` pre-release phases. |
| 58 | + |
| 59 | +### Minor Releases |
| 60 | + |
| 61 | +The go-cose project will issue minor releases when incremental improvements, or bug fixes are added to existing functionality. |
| 62 | +Minor releases will increment the minor field within the [semver][sem-ver] format. |
| 63 | + |
| 64 | +Each minor release will go through one or more `-alpha.n` and `-rc.n` pre-release phases. |
| 65 | + |
| 66 | +### Patch Releases |
| 67 | + |
| 68 | +Patch Releases include bug and security fixes. |
| 69 | +Patches will branch from the released branch being patched. |
| 70 | +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. |
| 71 | +If a bug fix requires new incremental, non-breaking change functionality, a new minor release may be issued. |
| 72 | + |
| 73 | +Principals of a patch release: |
| 74 | + |
| 75 | +- Should be a "safe bet" to upgrade to. |
| 76 | +- No breaking changes. |
| 77 | +- No feature or surface area changes. |
| 78 | +- A "bug fix" that may be a breaking change may require a major release. |
| 79 | +- Applicable fixes, including security fixes, may be cherry-picked from main into the latest supported minor release-X.Y branches. |
| 80 | +- Patch releases are cut from a release-X.Y.Z branch. |
| 81 | + |
| 82 | +Each patch release will go through one or more `-alpha.n` and `-rc.n` pre-release phases. |
| 83 | + |
| 84 | +### Pre-Release |
| 85 | + |
| 86 | +As builds of main become stable, and a pending release is planned, a pre-release build will be made. |
| 87 | +Pre-releases go through one or more `-alpha.n` releases, followed by one or more incremental `-rc.n` releases. |
| 88 | + |
| 89 | +- **alpha.n:** `X.Y.Z-alpha.n` |
| 90 | + - alpha release, cut from the branch where development occurs. |
| 91 | +To minimize branch management, no additional branches are maintained for each incremental release. |
| 92 | + - Considered an unstable release which should only be used for early development purposes. |
| 93 | + - Released incrementally until no additional issues and prs are made against the release. |
| 94 | + - Once no triaged issues or pull requests (prs) are scoped to the release, a release candidate (rc) is cut. |
| 95 | + - 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. |
| 96 | +Maintainers will create an Issue, and vote upon it for transparency to the decision to remove a release and/or branch. |
| 97 | + - Not [supported](#supported-releases) |
| 98 | +- **rc.n:** `X.Y.Z-rc.n` |
| 99 | + - Released as needed before a final version is released |
| 100 | + - Bugfixes on new features only as reported through usage |
| 101 | + - An rc is not expected to revert to an alpha release. |
| 102 | + - Once no triaged issues or prs are scoped to the release, an final version is cut. |
| 103 | + - A release candidate will typically have at least two weeks of bake time, providing the community time to provide feedback. |
| 104 | + - Release candidates are cut from the branch where the work is done. |
| 105 | + - 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. |
| 106 | +Maintainers will create an Issue, and vote upon it for transparency to the decision to remove a release and/or branch. |
| 107 | + - Not [supported](#supported-releases) |
| 108 | + |
| 109 | +## Supported Releases |
| 110 | + |
| 111 | +The go-cose maintainers expect to "support" n (current) and n-1 major.minor releases. |
| 112 | +"Support" means we expect users to be running that version in production. |
| 113 | +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. |
| 114 | +Support will be provided best effort by the maintainers via GitHub issues and pull requests from the community. |
| 115 | + |
| 116 | +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. |
| 117 | +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. |
| 118 | + |
| 119 | +While pre-releases may be deleted at the discretion of the maintainers, all Major, Minor and Patch releases should be maintained. |
| 120 | +Only in extreme circumstances, as agreed upon by a [two-thirds supermajority][super-majority] of the maintainers, shall a release be removed. |
| 121 | + |
| 122 | +Applicable fixes, including security fixes, may be cherry-picked into the release branch, depending on severity and feasibility. |
| 123 | +Patch releases are cut from that branch as needed. |
| 124 | + |
| 125 | +## Security Reviews |
| 126 | + |
| 127 | +The go-cose library is an sdk around underlying crypto libraries, tailored to COSE scenarios. |
| 128 | +The go-cose library does not implement cryptographic functionality, reducing the potential risk. |
| 129 | +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 |
| 130 | + |
| 131 | +For each release, new security reviews are evaluated by the maintainers as required or optional. |
| 132 | +The go-cose project welcomes additional security reviews. |
| 133 | +See [SECURITY.md](./SECURITY.md) for more information. |
| 134 | + |
| 135 | +## Glossary of Terms |
| 136 | + |
| 137 | +- **X.Y.Z** refers to the version (based on git tag) of go-cose that is released. |
| 138 | +This is the version of the go-cose binary. |
| 139 | +- **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. |
| 140 | +- **Milestone** GitHub milestones are used by maintainers to manage each release. |
| 141 | +PRs and Issues for each release should be created as part of a corresponding milestone. |
| 142 | +- **Patch releases** refer to applicable fixes, including security fixes, may be backported to support releases, depending on severity and feasibility. |
| 143 | + |
| 144 | +## Attribution |
| 145 | + |
| 146 | +This document builds on the ideas and implementations of release processes from the [notation](https://github.com/notaryproject/notation) project. |
| 147 | + |
| 148 | +[go-cose]: https://github.com/veraison/go-cose |
| 149 | +[ietf-cose]: https://datatracker.ietf.org/group/cose/about/ |
| 150 | +[sem-ver]: https://semver.org |
| 151 | +[releases]: https://github.com/veraison/go-cose/releases |
| 152 | +[super-majority]: https://en.wikipedia.org/wiki/Supermajority#Two-thirds_vote |
0 commit comments