github.com/opencontainers/umoci@v0.4.8-0.20240508124516-656e4836fb0d/RELEASES.md (about) 1 <!-- 2 +++ 3 # Hugo Front-matter 4 title = "Release Procedure" 5 aliases = ["/RELEASES.md"] 6 +++ 7 --> 8 9 ## Release Procedure ## 10 11 This document describes the procedure for preparing and publishing an umoci 12 release. Note that in order for a release of umoci to be approved, it must 13 follow the [approval procedure described in `GOVERNANCE.md`][governance]. 14 15 [governance]: /GOVERNANCE.md 16 17 ### Changelog ### 18 19 Before anything else, you must update the `CHANGELOG.md` to match the release. 20 This boils down to adding a new header underneath the "Unreleased" header so 21 that all of the changes are listed as being part of the new release. 22 23 ```diff 24 ## [Unreleased] 25 + 26 +## [X.Y.Z] - 20YY-MM-DD 27 - Changed FooBar to correctly Baz. 28 ``` 29 30 And then the `[X.Y.Z]` reference needs to be added and the `[Unreleased]` 31 reference updated. These links just show the set of commits added between 32 successive versions: 33 34 ```markdown 35 [Unreleased]: https://github.com/opencontainers/umoci/compare/vX.Y.Z...HEAD 36 [X.Y.Z]: https://github.com/opencontainers/umoci/compare/vX.Y.W...vX.Y.Z 37 [X.Y.W]: https://github.com/opencontainers/umoci/compare/vX.Y.V...vX.Y.W 38 ``` 39 40 The changes to `CHANGELOG.md` will be committed in the next section. 41 42 ### Pull Request ### 43 44 Releases need to be associated with a specific commit, with the release commit 45 being voted on by the maintainers ([as described in `GOVERNANCE.md`][governance]). 46 To prepare the pull request, the following steps are necessary: 47 48 ```ShellSession 49 % git branch release-X.Y.Z origin/master 50 % vi CHANGELOG.md # make the changes outlined above 51 % echo "X.Y.Z" > VERSION 52 % git commit -asm "VERSION: release X.Y.Z" # this is the release commit 53 % echo "X.Y.Z+dev" > VERSION 54 % git commit -asm "VERSION: back to development" 55 % git push # ... 56 ``` 57 58 And then [open a pull request][new-pr] with the `release-X.Y.Z` branch. If the 59 release requires a formal vote, the vote motion must specify the **release 60 commit** which is being considered (preferably both in the body and subject). 61 62 [governance]: /GOVERNANCE.md 63 [new-pr]: https://github.com/opencontainers/umoci/compare 64 65 ### Release Notes ### 66 67 The release notes (as published on the [releases page][releases]) are largely 68 based on the contents of `CHANGELOG.md` for the relevant release. However, any 69 important information (such as deprecation warnings or security fixes) should 70 be included in the release notes above the changelog. 71 72 In addition, the release notes should contain a list of the contributors to the 73 release. The simplest way of doing this is to just use the author information 74 from Git: 75 76 ```ShellSession 77 % git log --pretty=format:'%aN <%ae>' $1 | sort -u 78 ``` 79 80 Thus the final release notes should look something like the following: 81 82 ```Markdown 83 **WARNING**: Feature FooBar is now considered deprecated and will be removed in 84 release X.Y.FOO. 85 86 + Change FooBarBaz to support Xyz. 87 * Update documentation of FooBar. 88 - Remove broken XyzFoo implementation. 89 90 Thanks to all of the people who made this release possible: 91 92 * Jane Citizen <jane.citizen@example.com> 93 * Joe Citizen <joe.citizen@example.com> 94 95 Signed-off-by: [Your Name and Email Here] 96 ``` 97 98 [releases]: https://github.com/opencontainers/umoci/releases 99 100 ### Tag ### 101 102 All release tags must be signed by a maintainer, and annotated with the release 103 notes which will be used on releases page. This can be done with `git tag -as`. 104 The set of valid keys to sign releases and artefacts is maintained [as part of 105 this repository in the `gpg-offline` format][umoci-keyring]. 106 107 [umoci-keyring]: /umoci.keyring 108 109 ### Artefacts ### 110 111 Once a release has been approved and tagged, the only thing left is to create 112 the set of release artefacts to attach to the release. This can be easily done 113 with `make release`, which will run `hack/release.sh` with the correct version 114 information and the release artefacts will be in `release/X.Y.Z`. 115 116 Note that you may need to explicitly specify the correct GPG key to use to sign 117 the artefacts, which can be done by specifying `GPG_KEYID=` during the `make 118 release` invocation.