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) [three business days 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 release data locally](#update-the-release-data-locally)
26 - [Publish the release](#publish-the-release)
27 - [Updating the release data](#updating-the-release-data)
28 - [Post-publishing tasks](#post-publishing-tasks)
29 - [Check the website](#check-the-website)
30 - [Send the announcement mail](#send-the-announcement-mail)
31 - [Send out the Security Advisory](#send-out-the-security-advisory)
32 - [Unfreeze the source repository](#unfreeze-the-source-repository)
33 - [Security fixes](#security-fixes)
34 - [Keep in touch](#keep-in-touch)
41 Apart from the basic operating system utilities, you must have the following
42 programs in you `$PATH`:
49 (note: this may not be a complete list)
53 You must have access to the following repositories:
55 - `git@github.openssl.org:openssl/openssl.git`
57 This is the usual main source repository
59 - `git@github.openssl.org:otc/tools.git`
61 This contains certain common tools
63 - `git@github.openssl.org:omc/data.git`
65 This contains files to be updated as part of any release
69 You must have a PGP / GnuPG key, and its fingerprint should be present in
70 the file `doc/fingerprints.txt` in the source of the immediately prior
75 To perform a release, you must have appropriate access to OpenSSL's
76 development host, dev.openssl.org. To test this, try to log in with ssh:
80 You must also check that you can perform tasks as the user 'openssl' on
81 dev.openssl.org. When you have successfully logged in, test your access to
86 ## A method for reviewing
88 For reviewing to take place, the release person and the reviewer need a way
89 to share changes that are being applied. Most commonly, that's done as PRs
90 (for normal releases) or security advisories (for undisclosed security
91 fixes) through Github.
93 Security advisories are created using the Github Security tab, and will
94 generate a private repository, to which you can add collaborators (the
95 reviewer, for instance), and use it to fix the issue via pull requests.
96 For more information, please read Github's [creating a security advisory],
97 including the "Next Steps" at the end of that page.
99 [creating a security advisory]:
100 <https://docs.github.com/en/free-pro-team@latest/github/managing-security-vulnerabilities/creating-a-security-advisory>
102 The release person and the reviewer are allowed to use other means to share
103 the commits to be reviewed if they desire.
105 The release person and the reviewer must have a conversation to confirm or
106 figure out how the review shall be done.
108 # Pre-publishing tasks
110 Some of the actions in this section need to be repeated for each OpenSSL
113 ## Prepare your repository checkouts
115 You will need to checkout at least three working trees:
117 - one for extra tools
119 git clone git@github.openssl.org:otc/tools.git tools
121 The resulting directory will be referred to as `$TOOLS`
123 - one for release data
125 git clone git@github.openssl.org:omc/data.git data
127 - At least one for openssl source
129 git clone git@github.openssl.org:openssl/openssl.git
131 If you're doing multiple releases in one go, there are many ways to deal
132 with it. One possibility, available since git 2.5, is to use `git
136 git worktree add ../openssl-1.1.1 OpenSSL_1_1_1-stable)
138 ## Freeze the source repository
140 Three business day before the release, freeze the main repository. This
141 locks out everyone but the named user, who is doing the release, from doing
142 any pushes. Someone other than the person doing the release should run the
145 This must be done from a checkout of `git@github.openssl.org:openssl/openssl.git`.
147 git push git@github.openssl.org:openssl/openssl.git master:refs/frozen/NAME
149 Where `NAME` is the github username of the user doing the release.
151 Note: it currently doesn't matter what source branch is used when pushing,
152 the whole repository is frozen either way. The example above uses master.
154 ## Make sure that the openssl source is up to date
156 The person doing the release and the reviewer should both sanity-check the
157 source to be released at this point. Checks to consider include building
158 and verifying that make test passes on multiple plaforms - Linux, Windows,
161 *NOTE: the files CHANGES and NEWS are called CHANGES.md and NEWS.md in
162 OpenSSL versions from version 3.0 and on*
164 For each source checkout, make sure that the CHANGES and NEWS files have
165 been updated and reviewed.
167 The NEWS file should contain a summary of any changes for the release;
168 for a security release, it's often simply a list of the CVEs addressed.
169 You should also update NEWS.md in the master branch to include details of
170 all releases. Only update the bullet points - do not change the release
171 date, keep it as **under development**.
173 Add any security fixes to the tree and commit them.
175 Make sure that the copyrights are updated. This script will update the
176 copyright markers and commit the changes (where $TOOLS stands for the
177 openssl-tools.git checkout directory):
179 $TOOLS/release-tools/do-copyright-year
181 Obtain approval for these commits from the reviewer and add the Release and
182 Reviewed-By trailers as required.
184 *Do* send the auto-generated commits to the reviewer and await their
187 *Do not push* changes to the main source repo at this stage.
188 (the main source repo being `git@github.openssl.org:openssl/openssl.git`)
190 ## Generate the tarball and announcement text
192 *The changes in this section should be made in your clone of the openssl
195 The method to generate a release tarball and announcement text has changed
196 with OpenSSL 3.0, so while we continue to make pre-3.0 OpenSSL releases,
197 there are two methods to be aware of.
199 Both methods will leave a handful of files, most importantly the release
200 tarball. When they are done, they display a set of instructions on how to
201 perform the publishing tasks, *please take note of them*.
203 After having run the release script, verify that its results are sensible.
204 Check the commits that were added, using for example `git log`. Check the
205 signed announcement .asc file. Check that the tarball length and hashes
206 match in the .md5, .sha1, .sha256, and review the announcment file.
208 *Do* send the auto-generated commits to the reviewer and await their
211 *Do not push* changes to the main source repo at this stage.
212 (the main source repo being `git@github.openssl.org:openssl/openssl.git`)
214 ### OpenSSL 3.0 and on
216 The release generating script is in the OpenSSL source checkout, and is
217 generally called like this:
219 dev/release.sh --reviewer=NAME
221 This script has a multitude of other options that are useful for specific
222 cases, and is also self-documented:
224 - To get a quick usage reminder:
226 dev/release.sh --help
230 dev/release.sh --manual
232 ### OpenSSL before 3.0
234 The release generating script is in the tools checkout, represented here
235 with $TOOLS, and is generally called like this:
237 $TOOLS/release-tools/mkrelease.pl --reviewer=NAME
239 The manual for that script is found in `$TOOLS/release-tools/MKRELEASE.md`
241 ## Update the release data locally
243 *The changes in this section should be made in your clone of the release
246 Update the newsflash.txt file. This normally is one or two lines. Just
247 copy and paste existing announcements making minor changes for the date and
248 version number as necessary. If there is an advisory then ensure you
249 include a link to it.
251 Update the vulnerabilities.xml file if appropriate.
253 If there is a Security Advisory then copy it into the secadv directory.
255 *Do* send the commits to the reviewer and await their approval.
257 Make a pull request from your changes, against the release data repo (the
258 release data repo being `git@github.openssl.org:omc/data.git`).
260 *Do not merge the pull request at this point*, even if the reviewer already
263 # Publish the release
265 *BE CAREFUL* This section makes everything visible and is therefore largely
266 irreversible. If you are performing a dry run then DO NOT perform any steps
269 Check that the release has been uploaded properly. The release tarballs and
270 associated files should be in ~openssl/dist/new. They should be owned by
271 the openssl userid and world-readable.
273 Copy the tarballs to appropriate directories. This can be done using the
274 do-release.pl script. See $TOOLS/release-tools/DO-RELEASE.md for a
275 description of the options. For example:
277 sudo -u openssl perl ~openssl/do-release.pl --copy --move
279 This will copy the relevant files to the website and move them from
280 `~openssl/dist/new` to `~openssl/dist/old` so they will not seen by a
281 subsequent release. Alternatively if you want to perform one release at a
282 time or copy/move the files manually, see below.
284 The do-release.pl script will display the commands you will need to issue to
285 send the announcement emails later. Keep a note of those commands for
288 Verify that the tarballs are available via FTP:
290 ftp://ftp.openssl.org/source/
292 And that they are ready for the website:
294 ls /var/www/openssl/source
296 *For OpenSSL 3.0 and on*, push your local changes to the main source repo as
297 instructed by `dev/release.sh`. You may want to sanity check the pushes by
298 inserting the `-n` (dry-run) option.
300 *For OpenSSL before 3.0*, simply push your local changes to the main source
301 repo, and please do remember to push the release tags as well. You may want to
302 sanity check the pushes by inserting the `-n` (dry-run) option. You must specify
303 the repository / remote and tag to be pushed:
305 git push <repository> <tagname>
307 ## Updating the release data
309 Merge the PR against the release data repo now.
311 When you do this, the website will get updated and a script to flush the
312 Akamai CDN cache will be run.
314 You can look at <https://automation.openssl.org/> to see the automation
315 builds in action. The builder called `web` is of particular interest.
317 You can also look at the result at <https://www-origin.openssl.org>; the
318 CDN-hosted www.openssl.org should get updated withing minutes later.
320 # Post-publishing tasks
324 Verify that the release notes, which are built from the CHANGES.md file
325 in the release, have been updated. This is done automatically by OpenSSL
326 automation; if you see a problem, check if the web build job has been
327 performed yet, you may have to wait a few minutes before it kicks in.
329 Wait for a while for the Akamai flush to work (normally within a few minutes).
330 Have a look at the website and news announcement at:
332 - <https://www.openssl.org/>
333 - <https://www.openssl.org/news/>
335 Check the download page has updated properly:
337 - <https://www.openssl.org/source/>
339 Check the notes look sensible at:
341 - <https://www.openssl.org/news/newslog.html>
343 Also check the notes here:
345 - <https://www.openssl.org/news/openssl-1.0.2-notes.html>
346 - <https://www.openssl.org/news/openssl-1.1.0-notes.html>
347 - <https://www.openssl.org/news/openssl-1.1.1-notes.html>
349 ## Send the announcement mail
351 Send out the announcements. Generic release announcement messages will be
352 created automatically by the build script and the commands you need to use
353 to send them were displayed when you executed do-release.pl above.
354 These are sent to openssl-users, openssl-project, and openssl-announce. They
355 should be sent from the account of the person that owns the key used for signing
356 the release announcement. Ensure that mutt is configured correctly - send a test
357 email first if necessary.
359 If do-release.pl was used with `--move` be sure to move the announcement
360 text files away from the staging directory after they have been sent. This
361 is done as follows (with VERSION replaced with the version of OpenSSL to
364 REPLYTO="openssl@openssl.org" mutt -s "OpenSSL version VERSION published" \
365 openssl-project openssl-users openssl-announce \
366 < /home/openssl/dist/new/openssl-VERSION.txt.asc
368 mv ~openssl/dist/new/openssl-VERSION.txt.asc ~openssl/dist/old
370 ## Send out the Security Advisory
372 *The secadv file mentioned in this section is the Security Advisory
373 that you copied into the release data repo, up in the section
374 [Update the release data locally](#update-the-release-data-locally)*
376 *This section is only applicable if this is a security release*
378 Start with signing the Security Advisory as yourself:
380 gpg --clearsign secadv_FILENAME.txt
382 Then copy the result to the temporary directory on dev.openssl.org:
384 scp secadv_FILENAME.txt.asc dev.openssl.org:/tmp
386 To finish, log in on dev.openssl.org and send the signed Security
387 Advisory by email as the user that signed the advisory, and then remove it:
389 REPLYTO="openssl@openssl.org" mutt -s "OpenSSL Security Advisory" \
390 openssl-project openssl-users openssl-announce \
391 </tmp/secadv_FILENAME.txt.asc
392 rm /tmp/secadv_FILENAME.txt.asc
394 Approve the openssl-announce email. Go to
395 <https://mta.openssl.org/mailman/admindb/openssl-announce>
396 and approve the messages.
398 Check the mailing list messages have arrived.
400 ## Unfreeze the source repository.
402 This must be done from a checkout of the main source repo.
404 git push --delete git@github.openssl.org:openssl/openssl.git \
409 If this release includes security fixes with a CVE then you should inform
410 MITRE about them. See the instructions at the top of cvepool.txt in omc.
412 Close the github advisory without pushing to github and remove the private
413 github fork if there was one.
417 Check mailing lists over the next few hours for reports of any success or
418 failure. If necessary fix these and in the worst case make another