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.