From bd87eeeceb0285bdc9926dd4a46e96498d4825a6 Mon Sep 17 00:00:00 2001 From: Sajay Antony Date: Wed, 21 Sep 2022 17:23:58 +0000 Subject: [PATCH] docs: Update release process docs with checklist Copy over the Release doc from opencontainers/runtime-spec/blob/main/RELEASES.md Signed-off-by: Sajay Antony --- RELEASES.md | 55 ++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 50 insertions(+), 5 deletions(-) diff --git a/RELEASES.md b/RELEASES.md index 028ec265..96a640b8 100644 --- a/RELEASES.md +++ b/RELEASES.md @@ -23,7 +23,7 @@ However, specification releases have special restrictions in the [OCI charter][c * They are the target of backwards compatibility (§7.g), and * They are subject to the OFWa patent grant (§8.d and e). -To avoid unfortunate side effects (onerous backwards compatibity requirements or Member resignations), the following additional procedures apply to specification releases: +To avoid unfortunate side effects (onerous backwards compatibility requirements or Member resignations), the following additional procedures apply to specification releases: ### Planning a release @@ -43,9 +43,54 @@ Specifications have a variety of different timelines in their lifecycle. * Pre-v1.0.0 specifications SHOULD release on a monthly cadence to garner feedback. * Major specification releases MUST release at least three release candidates spaced a minimum of one week apart. - This means a major release like a v1.0.0 or v2.0.0 release will take 1 month at minimum: one week for rc1, one week for rc2, one week for rc3, and one week for the major release itself. - Maintainers SHOULD strive to make zero breaking changes during this cycle of release candidates and SHOULD restart the three-candidate count when a breaking change is introduced. - For example if a breaking change is introduced in v1.0.0-rc2 then the series would end with v1.0.0-rc4 and v1.0.0. + This means a major release like a v1.0.0 or v2.0.0 release will take 1 month at minimum: one week for rc1, one week for rc2, one week for rc3, and one week for the major release itself. + Maintainers SHOULD strive to make zero breaking changes during this cycle of release candidates and SHOULD restart the three-candidate count when a breaking change is introduced. + For example if a breaking change is introduced in v1.0.0-rc2 then the series would end with v1.0.0-rc4 and v1.0.0. * Minor and patch releases SHOULD be made on an as-needed basis. -[charter]: https://www.opencontainers.org/about/governance +[charter]: https://github.com/opencontainers/tob/blob/main/CHARTER.md + +## Checklist + +Releases usually follow a few steps: + +* [ ] prepare a pull-request for the release + * [ ] a commit updating `./ChangeLog` + * [ ] `git log --oneline --no-merges --decorate --name-status v1.0.1..HEAD | vim -` + * [ ] `:% s/(pr\/\(\d*\))\(.*\)/\2 (#\1)/` to move the PR to the end of line and match previous formatting + * [ ] review `(^M|^A|^D)` for impact of the commit + * [ ] group commits to `Additions:`, `Minor fixes and documentation:`, `Breaking changes:` + * [ ] delete the `(^M|^A|^D)` lines, `:%!grep -vE '(^M|^A|^D)'` + * [ ] merge multi-commit PRs (so each line has a `(#num)` suffix) + * [ ] drop hash and indent, `:'<,'> s/^\w* /^I* /` + * [ ] a commit bumping `./specs-go/version.go` to next version and empty the `VersionDev` variable + * [ ] a commit adding back the "-dev" to `VersionDev` +* [ ] send email to dev@opencontainers.org + * [ ] copy the exact commit hash for bumping the version from the pull-request (since master always stays as "-dev") + * [ ] count the PRs since last release (that this version is tracking, in the cases of multiple branching), like `git log --pretty=oneline --no-merges --decorate $priorTag..$versionBumpCommit | grep \(pr\/ | wc -l` + * [ ] get the date for a week from now, like `TZ=UTC date --date='next week'` + * [ ] OPTIONAL find a cute animal gif to attach to the email, and subsequently the release description + * [ ] subject line like `[runtime-spec VOTE] tag $versionBumpCommit as $version (closes $dateWeekFromNowUTC)` + * [ ] email body like +``` +Hey everyone, + +There have been $numPRs PRs merged since $priorTag release (https://github.com/opencontainers/runtime-spec/compare/$priorTag...$versionBumpCommit). + +$linkToPullRequest + +Please respond LGTM or REJECT (with reasoning). + +$sig +``` +* [ ] edit/update the pull-request to link to the VOTE thread, from https://groups.google.com/a/opencontainers.org/forum/#!forum/dev +* [ ] a week later, if the vote passes, merge the PR + * [ ] `git tag -s $version $versionBumpCommit` + * [ ] `git push --tags` +* [ ] produce release documents + * [ ] git checkout the release tag, like `git checkout $version` + * [ ] `make docs` + * [ ] rename the output PDF and HTML file to include version, like `mv output/oci-runtime-spec.pdf output/oci-runtime-spec-$version.pdf`` + * [ ] attach these docs to the release on https://github.com/opencontainers/runtime-spec/releases + * [ ] link to the the VOTE thread and include the passing vote count + * [ ] link to the pull request that merged the release