HOWTO-make-a-release.md

   1 # HOW TO MAKE A RELEASE
   2
   3 This file documents the overall OpenSSL release process.  Some parts of this
   4 process is documented in other files that go into deeper detail.
   5
   6 # Table of contents
   7
   8 -   [Prerequisites](#prerequisites)
   9     -   [Software](#software)
  10     -   [Repositories](#repositories)
  11     -   [A method for reviewing](#a-method-for-reviewing)
  12 -   [Preparation tasks](#preparation-tasks)
  13     -   [Freeze the source repository](#freeze-the-source-repository) [three business days before release]
  14     -   [Make sure that the openssl source is up to date](#make-sure-that-the-openssl-source-is-up-to-date)
  15 -   [Stage the release](#stage-the-release)
  16 -   [Publish the release](#publish-the-release)
  17 -   [Post-releasing tasks](#post-publishing-tasks)
  18     -   [Unfreeze the source repository](#unfreeze-the-source-repository)
  19     -   [Keep in touch](#keep-in-touch)
  20
  21
  22 # Prerequisites
  23
  24 ## Software
  25
  26 Apart from the basic operating system utilities, you must have the following
  27 programs in you `$PATH`:
  28
  29 - ssh
  30 - git
  31
  32 (note: this may not be a complete list)
  33
  34 ## Repositories
  35
  36 You must have access to the following repositories:
  37
  38 -   `git@github.openssl.org:openssl/openssl.git`
  39
  40     This is the public source repository, so is only necessary to stage
  41     a public release, which are those that haven't reached End-Of-Life
  42     yet.
  43
  44 -   `git@github.openssl.org:openssl/security.git`
  45
  46     This is the security source repository, where security fixes are
  47     staged before being publically released.  It is used as source
  48     repository instead of `openssl/openssl` to stage a security
  49     release.
  50
  51 -   `git@github.openssl.org:openssl/premium.git`
  52
  53     This is the source repository for premium customers, used for both
  54     security and non-security releases.
  55
  56 ## A method for reviewing
  57
  58 In some parts of the release process, peer review may apply.  The review
  59 methods are specified in more detail in those parts.
  60
  61 # Preparation tasks
  62
  63 Some of the actions in this section need to be repeated for each OpenSSL
  64 version released.
  65
  66 ## Prepare your repository checkouts
  67
  68 -   For each release to be staged, you need to checkout its source
  69     repository, which is one of:
  70
  71     -   `git clone git@github.openssl.org:openssl/openssl.git`
  72     -   `git clone git@github.openssl.org:openssl/security.git`
  73     -   `git clone git@github.openssl.org:openssl/premium.git`
  74
  75 ## Freeze the source repository
  76
  77 Three business day before the release, freeze the appropriate source
  78 repository.
  79
  80 This locks out everyone but the named user, who is doing the release, from
  81 doing any pushes.  Someone other than the person doing the release should
  82 run the command.
  83
  84 This must be done from a checkout of that source repository, so for public
  85 as well as security releases:
  86
  87     git push git@github.openssl.org:openssl/openssl.git HEAD:refs/frozen/NAME
  88
  89 and for premium releases:
  90
  91     git push git@github.openssl.org:openssl/premium.git HEAD:refs/frozen/NAME
  92
  93 Where `NAME` is the github username of the user doing the release.
  94
  95 Note: it currently doesn't matter what source branch is used when pushing,
  96 the whole repository is frozen either way.  The example above uses whatever
  97 branch you happen to have checked out.
  98
  99 Note: `git@github.openssl.org:openssl/security.git` is derived from
 100 `git@github.openssl.org:openssl/openssl.git`, so when freezing the latter,
 101 it's implied that the former is frozen as well.
 102
 103 ## Notify comitters and platform owners of the freeze
 104
 105 When the tree is frozen, an email should be sent to openssl-comitters@openssl.org, as well as to the community platform owners (documented [here](https://www.openssl.org/policies/general-supplemental/platforms.html))indicating that the tree is frozen, and how long the freeze is expected to last.  It should also indicate to the community platform owners that additional, more frequent testing during the freeze would be appreciated, as community platforms are not all in our CI system.  This will help mitigate inadvertent breakage during the freeze period on platforms we do not consistently test against.
 106
 107
 108 ## Make sure that the openssl source is up to date
 109
 110 For security releases, merge all applicable and approved security PRs.
 111
 112 *NOTE: the files CHANGES.md and NEWS.md are called CHANGES and NEWS in
 113 OpenSSL versions before version 3.0*
 114
 115 For each source checkout, make sure that the CHANGES.md and NEWS.md files
 116 have been updated and reviewed.
 117
 118 The NEWS file should contain a summary of any changes for the release;
 119 for a security release, it's often simply a list of the CVEs addressed.
 120 You should also update NEWS.md in the master branch to include details of
 121 all releases.  Only update the bullet points - do not change the release
 122 date, keep it as **under development**.
 123
 124 # Stage the release
 125
 126 See [HOWTO-stage-a-release.md](HOWTO-stage-a-release.md), which describes
 127 this in detail.
 128
 129 This may be done independently of [publishing the release](#publish-the-release).
 130 However, if done manually, the same person should stage and publish the
 131 release, as doing it this way depends on that person's local clones and
 132 checkouts.
 133
 134 # Publish the release
 135
 136 See [HOWTO-publish-a-release.md](HOWTO-publish-a-release.md), which
 137 describes this in detail.
 138
 139 This may be done independently of [staging the release](#stage-the-release).
 140 However, if done manually, the same person should stage and publish the
 141 release, as doing it this way depends on that person's local clones and
 142 checkouts.
 143
 144 # Post-releasing tasks
 145
 146 ## Unfreeze the source repository.
 147
 148 This must be done from a checkout of the appropriate source repo:
 149
 150     git push --delete git@github.openssl.org:openssl/openssl.git \
 151         refs/frozen/NAME
 152
 153 or:
 154
 155     git push --delete git@github.openssl.org:openssl/premium.git \
 156         refs/frozen/NAME
 157
 158 ## Keep in touch
 159
 160 Check mailing lists over the next few hours for reports of any success or
 161 failure.  If necessary fix these and in the worst case make another
 162 release.