1 # HOW TO MAKE A RELEASE
3 This file documents how to make an OpenSSL release. Please fix any errors
4 you find while doing, or just after, your next release!
6 Releases are done by one person, with a second person acting as the reviewer
11 - [Prerequisites](#prerequisites)
12 - [Software](#software)
13 - [Repositories](#repositories)
14 - [PGP / GnuPG key](#pgp-gnupg-key)
15 - [SSH access](#check-your-access)
16 - [A method for reviewing](#a-way-to-reviewing)
17 - [Pre-publishing tasks](#pre-publishing-tasks)
18 - [Prepare your repository checkouts](#prepare-your-repository-checkouts)
19 - [Freeze the source repository](#freeze-the-source-repository) [the day before release]
20 - [Make sure that the openssl source is up to date](#make-sure-that-the-openssl-source-is-up-to-date)
21 - [Generate the tarball and announcement text](#generating-the-tarball-and-announcement-text)
22 - [OpenSSL 3.0 and on](#openssl-3.0-and-on)
23 - [OpenSSL before 3.0](#openssl-before-3.0)
24 - [Update the website locally](#update-the-website-locally) [do not push]
25 - [Publish the release](#publish-the-release)
26 - [Post-publishing tasks](#post-publishing-tasks)
27 - [Check the website](#check-the-website)
28 - [Send the announcement mail](#send-the-announcement-mail)
29 - [Send out the Security Advisory](#send-out-the-security-advisory)
30 - [Unfreeze the source repository](#unfreeze-the-source-repository)
31 - [Security fixes](#security-fixes)
32 - [Keep in touch](#keep-in-touch)
39 Apart from the basic operating system utilities, you must have the following
40 programs in you `$PATH`:
47 (note: this may not be a complete list)
51 You must have access to the following repositories:
53 - `git@github.openssl.org:openssl/openssl.git`
55 This is the usual main source repository
57 - `git@github.openssl.org:openssl/web.git`
59 This is the website repository
61 - `git@github.openssl.org:otc/tools.git`
63 This contains certain common tools
67 You must have a PGP / GnuPG key, and its fingerprint should be present in
68 the file `doc/fingerprints.txt` in the source of the immediately prior
73 To perform a release, you must have appropriate access to OpenSSL's
74 development host, dev.openssl.org. To test this, try to log in with ssh:
78 You must also check that you can perform tasks as the user 'openssl' on
79 dev.openssl.org. When you have successfully logged in, test your access to
84 ## A method for reviewing
86 For reviewing to take place, the release person and the reviewer need a way
87 to share changes that are being applied. Most commonly, that's done as PRs
88 (for normal releases) or security advisories (for undisclosed security
89 fixes) through Github.
91 Security advisories are created using the Github Security tab, and will
92 generate a private repository, to which you can add collaborators (the
93 reviewer, for instance), and use it to fix the issue via pull requests.
94 For more information, please read Github's [creating a security advisory],
95 including the "Next Steps" at the end of that page.
97 [creating a security advisory]:
98 <https://docs.github.com/en/free-pro-team@latest/github/managing-security-vulnerabilities/creating-a-security-advisory>
100 The release person and the reviewer are allowed to use other means to share
101 the commits to be reviewed if they desire.
103 The release person and the reviewer must have a conversation to confirm or
104 figure out how the review shall be done.
106 # Pre-publishing tasks
108 Some of the actions in this section need to be repeated for each OpenSSL
111 ## Prepare your repository checkouts
113 You will need to checkout at least three working trees:
115 - one for the website
117 git clone git@github.openssl.org:openssl/web.git website
119 - one for extra tools
121 git clone git@github.openssl.org:otc/tools.git tools
123 The resulting directory will be referred to as `$TOOLS`
125 - At least one for openssl source
127 git clone git@github.openssl.org:openssl/openssl.git
129 If you're doing multiple releases in one go, there are many ways to deal
130 with it. One possibility, available since git 2.5, is to use `git
134 git worktree add ../openssl-1.1.1 OpenSSL_1_1_1-stable)
136 ## Freeze the source repository
138 Three business day before the release, freeze the main repository. This
139 locks out everyone but the named user, who is doing the release, from doing
140 any pushes. Someone other than the person doing the release should run the
143 This must be done from a checkout of `git@github.openssl.org:openssl/openssl.git`.
145 git push git@github.openssl.org:openssl/openssl.git refs/frozen/NAME
147 Where `NAME` is the github username of the user doing the release.
149 ## Make sure that the openssl source is up to date
151 The person doing the release and the reviewer should both sanity-check the
152 source to be released at this point. Checks to consider include building
153 and verifying that make test passes on multiple plaforms - Linux, Windows,
156 *NOTE: the files CHANGES and NEWS are called CHANGES.md and NEWS.md in
157 OpenSSL versions from version 3.0 and on*
159 For each source checkout, make sure that the CHANGES and NEWS files have
160 been updated and reviewed.
162 The NEWS file should contain a summary of any changes for the release;
163 for a security release, it's often simply a list of the CVEs addressed.
164 You should also update NEWS.md in the master branch to include details of
165 all releases. Only update the bullet points - do not change the release
166 date, keep it as **under development**.
168 Add any security fixes to the tree and commit them.
170 Make sure that the copyrights are updated. This script will update the
171 copyright markers and commit the changes (where $TOOLS stands for the
172 openssl-tools.git checkout directory):
174 $TOOLS/release-tools/do-copyright-year
176 Obtain approval for these commits from the reviewer and add the Release and
177 Reviewed-By trailers as required.
179 *Do* send the auto-generated commits to the reviewer and await their
182 *Do not push* changes to the main source repo at this stage.
183 (the main source repo being `git@github.openssl.org:openssl/openssl.git`)
185 ## Generate the tarball and announcement text
187 *The changes in this section should be made in your clone of the openssl
190 The method to generate a release tarball and announcement text has changed
191 with OpenSSL 3.0, so while we continue to make pre-3.0 OpenSSL releases,
192 there are two methods to be aware of.
194 Both methods will leave a handful of files, most importantly the release
195 tarball. When they are done, they display a set of instructions on how to
196 perform the publishing tasks, *please take note of them*.
198 After having run the release script, verify that its results are sensible.
199 Check the commits that were added, using for example `git log`. Check the
200 signed announcement .asc file. Check that the tarball length and hashes
201 match in the .md5, .sha1, .sha256, and review the announcment file.
203 *Do* send the auto-generated commits to the reviewer and await their
206 *Do not push* changes to the main source repo at this stage.
207 (the main source repo being `git@github.openssl.org:openssl/openssl.git`)
209 ### OpenSSL 3.0 and on
211 The release generating script is in the OpenSSL source checkout, and is
212 generally called like this:
214 dev/release.sh --reviewer=NAME
216 This script has a multitude of other options that are useful for specific
217 cases, and is also self-documented:
219 - To get a quick usage reminder:
221 dev/release.sh --help
225 dev/release.sh --manual
227 ### OpenSSL before 3.0
229 The release generating script is in the tools checkout, represented here
230 with $TOOLS, and is generally called like this:
232 $TOOLS/release-tools/mkrelease.pl --reviewer=NAME
234 The manual for that script is found in `$TOOLS/release-tools/MKRELEASE.md`
236 ## Update the website locally
238 *The changes in this section should be made in your clone of the openssl
241 Update the news/newsflash.txt file. This normally is one or two lines.
242 Just copy and paste existing announcements making minor changes for the date
243 and version number as necessary. If there is an advisory then ensure you
244 include a link to it.
246 Update the news/vulnerabilities.xml file if appropriate.
248 If there is a Security Advisory then copy it into the news/secadv directory.
250 *Do* send the commits to the reviewer and await their approval.
252 Commit your changes, but *do not push* them to the website repo at this stage.
253 (the website repo being `git@github.openssl.org:openssl/web.git`)
255 # Publish the release
257 *BE CAREFUL* This section makes everything visible and is therefore largely
258 irreversible. If you are performing a dry run then DO NOT perform any steps
261 Check that the release has been uploaded properly. The release tarballs and
262 associated files should be in ~openssl/dist/new. They should be owned by
263 the openssl userid and world-readable.
265 Copy the tarballs to appropriate directories. This can be done using the
266 do-release.pl script. See $TOOLS/release-tools/DO-RELEASE.md for a
267 description of the options. For example:
269 sudo -u openssl perl ~openssl/do-release.pl --copy --move
271 This will copy the relevant files to the website and move them from
272 `~openssl/dist/new` to `~openssl/dist/old` so they will not seen by a
273 subsequent release. Alternatively if you want to perform one release at a
274 time or copy/move the files manually, see below.
276 The do-release.pl script will display the commands you will need to issue to
277 send the announcement emails later. Keep a note of those commands for
280 Verify that the tarballs are available via FTP:
282 ftp://ftp.openssl.org/source/
284 And that they are ready for the website:
286 ls /var/www/openssl/source
288 *For OpenSSL 3.0 and on*, push your local changes to the main source repo as
289 instructed by `dev/release.sh`. You may want to sanity check the pushes by
290 inserting the `-n` (dry-run) option.
292 *For OpenSSL before 3.0*, simply push your local changes to the main source
293 repo, and please do remember to push the release tags as well. You may want to
294 sanity check the pushes by inserting the `-n` (dry-run) option. You must specify
295 the repository / remote and tag to be pushed:
297 git push <repository> <tagname>
299 ## Updating the website
301 Push the website changes you made earlier to the OpenSSL website repo. When
302 you do this, the website will get updated and a script to flush the Akamai
303 CDN cache will be run. You can look at things on www-origin.openssl.org;
304 the CDN-hosted www.openssl.org should only be a few minutes delayed.
306 # Post-publishing tasks
310 Verify that the release notes, which are built from the CHANGES.md file
311 in the release, have been updated. This is done automatically by the
312 commit-hook, but if you see a problem, try the following steps on
316 sudo -u openssl -H make relupd
317 sudo -u openssl -H ./bin/purge-one-hour
319 Wait for a while for the Akamai flush to work (normally within a few minutes).
320 Have a look at the website and news announcement at:
322 - <https://www.openssl.org/>
323 - <https://www.openssl.org/news/>
325 Check the download page has updated properly:
327 - <https://www.openssl.org/source/>
329 Check the notes look sensible at:
331 - <https://www.openssl.org/news/newslog.html>
333 Also check the notes here:
335 - <https://www.openssl.org/news/openssl-1.0.2-notes.html>
336 - <https://www.openssl.org/news/openssl-1.1.0-notes.html>
337 - <https://www.openssl.org/news/openssl-1.1.1-notes.html>
339 ## Send the announcement mail
341 Send out the announcements. Generic release announcement messages will be
342 created automatically by the build script and the commands you need to use
343 to send them were displayed when you executed do-release.pl above.
344 These are sent to openssl-users, openssl-project, and openssl-announce. They
345 should be sent from the account of the person that owns the key used for signing
346 the release announcement. Ensure that mutt is configured correctly - send a test
347 email first if necessary.
349 If do-release.pl was used with `--move` be sure to move the announcement
350 text files away from the staging directory after they have been sent. This
351 is done as follows (with VERSION replaced with the version of OpenSSL to
354 REPLYTO="openssl@openssl.org" mutt -s "OpenSSL version VERSION published" \
355 openssl-project openssl-users openssl-announce \
356 < /home/openssl/dist/new/openssl-VERSION.txt.asc
358 mv ~openssl/dist/new/openssl-VERSION.txt.asc ~openssl/dist/old
360 ## Send out the Security Advisory
362 *The secadv file mentioned in this section is the Security Advisory
363 that you copied into the web repo, up in the section
364 [Update the website locally](#update-the-website-locally)*
366 *This section is only applicable if this is a security release*
368 Start with signing the Security Advisory as yourself:
370 gpg --clearsign secadv_FILENAME.txt
372 Then copy the result to the temporary directory on dev.openssl.org:
374 scp secadv_FILENAME.txt.asc dev.openssl.org:/tmp
376 To finish, log in on dev.openssl.org and send the signed Security
377 Advisory by email as the user that signed the advisory, and then remove it:
379 REPLYTO="openssl@openssl.org" mutt -s "OpenSSL Security Advisory" \
380 openssl-project openssl-users openssl-announce \
381 </tmp/secadv_FILENAME.txt.asc
382 rm /tmp/secadv_FILENAME.txt.asc
384 Approve the openssl-announce email. Go to
385 <https://mta.openssl.org/mailman/admindb/openssl-announce>
386 and approve the messages.
388 Check the mailing list messages have arrived.
390 ## Unfreeze the source repository.
392 This must be done from a checkout of the main source repo.
394 git push --delete git@github.openssl.org:openssl/openssl.git \
399 If this release includes security fixes with a CVE then you should inform
400 MITRE about them. See the instructions at the top of cvepool.txt in omc.
402 Close the github advisory without pushing to github and remove the private
403 github fork if there was one.
407 Check mailing lists over the next few hours for reports of any success or
408 failure. If necessary fix these and in the worst case make another