mirror of https://github.com/openssl/tools
New releasing instructions, HOWTO-make-a-release.md
README.md in $TOOLS/release-tools/ isn't obvious to discover. It has also aged considerably, at least in terms of OpenSSL 3.0, so needs a serious update. Co-authored-by: Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com> Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/tools/pull/75)
This commit is contained in:
Richard Levitte
parent
af3ebdeb6c
commit
e1fc98e1c1
|
|
@ -0,0 +1,400 @@
|
|||
# HOW TO MAKE A RELEASE
|
||||
|
||||
This file documents how to make an OpenSSL release. Please fix any errors
|
||||
you find while doing, or just after, your next release!
|
||||
|
||||
Releases are done by one person, with a second person acting as the reviewer
|
||||
and additional tester.
|
||||
|
||||
# Table of contents
|
||||
|
||||
- [Prerequisites](#prerequisites)
|
||||
- [Software](#software)
|
||||
- [Repositories](#repositories)
|
||||
- [PGP / GnuPG key](#pgp-gnupg-key)
|
||||
- [SSH access](#check-your-access)
|
||||
- [A method for reviewing](#a-way-to-reviewing)
|
||||
- [Pre-publishing tasks](#pre-publishing-tasks)
|
||||
- [Freeze the source repository](#freeze-the-source-repository) [the day before release]
|
||||
- [Prepare your repository checkouts](#prepare-your-repository-checkouts)
|
||||
- [Make sure that the openssl source is up to date](#make-sure-that-the-openssl-source-is-up-to-date)
|
||||
- [Generate the tarball and announcement text](#generating-the-tarball-and-announcement-text)
|
||||
- [OpenSSL 3.0 and on](#openssl-3.0-and-on)
|
||||
- [OpenSSL before 3.0](#openssl-before-3.0)
|
||||
- [Update the website locally](#update-the-website-locally) [do not push]
|
||||
- [Publish the release](#publish-the-release)
|
||||
- [Post-publishing tasks](#post-publishing-tasks)
|
||||
- [Check the website](#check-the-website)
|
||||
- [Send the announcement mail](#send-the-announcement-mail)
|
||||
- [Send out the Security Advisory](#send-out-the-security-advisory)
|
||||
- [Unfreeze the source repository](#unfreeze-the-source-repository)
|
||||
- [Security fixes](#security-fixes)
|
||||
- [Keep in touch](#keep-in-touch)
|
||||
|
||||
|
||||
# Prerequisites
|
||||
|
||||
## Software
|
||||
|
||||
Apart from the basic operating system utilities, you must have the following
|
||||
programs in you `$PATH`:
|
||||
|
||||
- openssl
|
||||
- ssh
|
||||
- gpg
|
||||
- git
|
||||
|
||||
(note: this may not be a complete list)
|
||||
|
||||
## Repositories
|
||||
|
||||
You must have access to the following repositories:
|
||||
|
||||
- `openssl-git@git.openssl.org:openssl.git`
|
||||
|
||||
This is the usual main source repository
|
||||
|
||||
- `openssl-git@git.openssl.org:openssl-web.git`
|
||||
|
||||
This is the website repository
|
||||
|
||||
- `openssl-git@git.openssl.org:tools.git`
|
||||
|
||||
This contains certain common tools
|
||||
|
||||
## PGP / GnuPG key
|
||||
|
||||
You must have a PGP / GnuPG key, and its fingerprint should be present in
|
||||
the file `doc/fingerprints.txt` in the source of the immediately prior
|
||||
OpenSSL release.
|
||||
|
||||
## SSH access
|
||||
|
||||
To perform a release, you must have appropriate access to OpenSSL's
|
||||
development host, dev.openssl.org. To test this, try to log in with ssh:
|
||||
|
||||
ssh dev.openssl.org
|
||||
|
||||
You must also check that you can perform tasks as the user 'openssl' on
|
||||
dev.openssl.org. When you have successfully logged in, test your access to
|
||||
that user with sudo:
|
||||
|
||||
sudo -u openssl id
|
||||
|
||||
## A method for reviewing
|
||||
|
||||
For reviewing to take place, the release person and the reviewer need a way
|
||||
to share changes that are being applied. Most commonly, that's done as PRs
|
||||
(for normal releases) or security advisories (for undisclosed security
|
||||
fixes) through Github.
|
||||
|
||||
Security advisories are created using the Github Security tab, and will
|
||||
generate a private repository, to which you can add collaborators (the
|
||||
reviewer, for instance), and use it to fix the issue via pull requests.
|
||||
For more information, please read Github's [creating a security advisory],
|
||||
including the "Next Steps" at the end of that page.
|
||||
|
||||
[creating a security advisory]:
|
||||
<https://docs.github.com/en/free-pro-team@latest/github/managing-security-vulnerabilities/creating-a-security-advisory>
|
||||
|
||||
The release person and the reviewer are allowed to use other means to share
|
||||
the commits to be reviewed if they desire.
|
||||
|
||||
The release person and the reviewer must have a conversation to confirm or
|
||||
figure out how the review shall be done.
|
||||
|
||||
# Pre-publishing tasks
|
||||
|
||||
Some of the actions in this section need to be repeated for each OpenSSL
|
||||
version released.
|
||||
|
||||
## Freeze the source repository
|
||||
|
||||
The day before the release, freeze the main repository. This locks out
|
||||
everyone but the named user, who is doing the release, from doing any
|
||||
pushes. Someone other than the person doing the release should run the
|
||||
command. For example:
|
||||
|
||||
ssh openssl-git@git.openssl.org freeze openssl NAME
|
||||
|
||||
## Prepare your repository checkouts
|
||||
|
||||
You will need to checkout at least three working trees:
|
||||
|
||||
- one for the website
|
||||
|
||||
git clone openssl-git@git.openssl.org:openssl-web.git website
|
||||
|
||||
- one for extra tools
|
||||
|
||||
git clone openssl-git@git.openssl.org:tools.git tools
|
||||
|
||||
The resulting directory will be referred to as `$TOOLS`
|
||||
|
||||
- At least one for openssl source
|
||||
|
||||
git clone openssl-git@git.openssl.org:openssl.git
|
||||
|
||||
If you're doing multiple releases in one go, there are many ways to deal
|
||||
with it. One possibility, available since git 2.5, is to use `git
|
||||
worktree`:
|
||||
|
||||
(cd openssl;
|
||||
git worktree add ../openssl-1.1.1 OpenSSL_1_1_1-stable)
|
||||
|
||||
## Make sure that the openssl source is up to date
|
||||
|
||||
The person doing the release and the reviewer should both sanity-check the
|
||||
source to be released at this point. Checks to consider include building
|
||||
and verifying that make test passes on multiple plaforms - Linux, Windows,
|
||||
etc.
|
||||
|
||||
*NOTE: the files CHANGES and NEWS are called CHANGES.md and NEWS.md in
|
||||
OpenSSL versions from version 3.0 and on*
|
||||
|
||||
For each source checkout, make sure that the CHANGES and NEWS files have
|
||||
been updated and reviewed.
|
||||
|
||||
The NEWS file should contain a summary of any changes for the release;
|
||||
for a security release, it's often simply a list of the CVEs addressed.
|
||||
You should also update NEWS.md in the master branch to include details of
|
||||
all releases. Only update the bullet points - do not change the release
|
||||
date, keep it as **under development**.
|
||||
|
||||
Add any security fixes to the tree and commit them.
|
||||
|
||||
Make sure that the copyrights are updated. This script will update the
|
||||
copyright markers and commit the changes (where $TOOLS stands for the
|
||||
openssl-tools.git checkout directory):
|
||||
|
||||
$TOOLS/release-tools/do-copyright-year
|
||||
|
||||
Obtain approval for these commits from the reviewer and add the reviewed-by
|
||||
headers as required.
|
||||
|
||||
*Do* send the auto-generated commits to the reviewer and await their
|
||||
approval.
|
||||
|
||||
*Do not push* changes to the main source repo at this stage.
|
||||
(the main source repo being `openssl-git@git.openssl.org:openssl.git`)
|
||||
|
||||
## Generate the tarball and announcement text
|
||||
|
||||
*The changes in this section should be made in your clone of the openssl
|
||||
source repo*
|
||||
|
||||
The method to generate a release tarball and announcement text has changed
|
||||
with OpenSSL 3.0, so while we continue to make pre-3.0 OpenSSL releases,
|
||||
there are two methods to be aware of.
|
||||
|
||||
Both methods will leave a handful of files, most importantly the release
|
||||
tarball. When they are done, they display a set of instructions on how to
|
||||
perform the publishing tasks, *please take note of them*.
|
||||
|
||||
After having run the release script, verify that its results are sensible.
|
||||
Check the commits that were added, using for example `git log`. Check the
|
||||
signed announcement .asc file. Check that the tarball length and hashes
|
||||
match in the .md5, .sha1, .sha256, and review the announcment file.
|
||||
|
||||
*Do* send the auto-generated commits to the reviewer and await their
|
||||
approval.
|
||||
|
||||
*Do not push* changes to the main source repo at this stage.
|
||||
(the main source repo being `openssl-git@git.openssl.org:openssl.git`)
|
||||
|
||||
### OpenSSL 3.0 and on
|
||||
|
||||
The release generating script is in the OpenSSL source checkout, and is
|
||||
generally called like this:
|
||||
|
||||
dev/release.sh --reviewer=NAME
|
||||
|
||||
This script has a multitude of other options that are useful for specific
|
||||
cases, and is also self-documented:
|
||||
|
||||
- To get a quick usage reminder:
|
||||
|
||||
dev/release.sh --help
|
||||
|
||||
- To get a man-page:
|
||||
|
||||
dev/release.sh --manual
|
||||
|
||||
### OpenSSL before 3.0
|
||||
|
||||
The release generating script is in the tools checkout, represented here
|
||||
with $TOOLS, and is generally called like this:
|
||||
|
||||
$TOOLS/release-tools/mkrelease.pl --reviewer=NAME
|
||||
|
||||
The manual for that script is found in `$TOOLS/release-tools/MKRELEASE.md`
|
||||
|
||||
## Update the website locally
|
||||
|
||||
*The changes in this section should be made in your clone of the openssl
|
||||
web repo*
|
||||
|
||||
Update the news/newsflash.txt file. This normally is one or two lines.
|
||||
Just copy and paste existing announcements making minor changes for the date
|
||||
and version number as necessary. If there is an advisory then ensure you
|
||||
include a link to it.
|
||||
|
||||
Update the news/vulnerabilities.xml file if appropriate.
|
||||
|
||||
If there is a Security Advisory then copy it into the news/secadv directory.
|
||||
|
||||
*Do* send the commits to the reviewer and await their approval.
|
||||
|
||||
Commit your changes, but *do not push* them to the website repo at this stage.
|
||||
(the website repo being `openssl-git@git.openssl.org:openssl-web.git`)
|
||||
|
||||
# Publish the release
|
||||
|
||||
*BE CAREFUL* This section makes everything visible and is therefore largely
|
||||
irreversible. If you are performing a dry run then DO NOT perform any steps
|
||||
in this section.
|
||||
|
||||
Check that the release has been uploaded properly. The release tarballs and
|
||||
associated files should be in ~openssl/dist/new. They should be owned by
|
||||
the openssl userid and world-readable.
|
||||
|
||||
Copy the tarballs to appropriate directories. This can be done using the
|
||||
do-release.pl script. See $TOOLS/release-tools/DO-RELEASE.md for a
|
||||
description of the options. For example:
|
||||
|
||||
sudo -u openssl perl ~openssl/do-release.pl --copy --move
|
||||
|
||||
This will copy the relevant files to the website and move them from
|
||||
`~openssl/dist/new` to `~openssl/dist/old` so they will not seen by a
|
||||
subsequent release. Alternatively if you want to perform one release at a
|
||||
time or copy/move the files manually, see below.
|
||||
|
||||
The do-release.pl script will display the commands you will need to issue to
|
||||
send the announcement emails later. Keep a note of those commands for
|
||||
future reference.
|
||||
|
||||
Verify that the tarballs are available via FTP:
|
||||
|
||||
ftp://ftp.openssl.org/source/
|
||||
|
||||
And that they are ready for the website:
|
||||
|
||||
ls /var/www/openssl/source
|
||||
|
||||
*For OpenSSL 3.0 and on*, push your local changes to the main source repo as
|
||||
instructed by `dev/release.sh`. You may want to sanity check the pushes by
|
||||
inserting the `-n` (dry-run) option.
|
||||
|
||||
*For OpenSSL before 3.0*, simply push your local changes to the main source
|
||||
repo, and please do remember to push the release tags as well, which is done
|
||||
separately with the `--tags` option. You may want to sanity check the
|
||||
pushes by inserting the `-n` (dry-run) option.
|
||||
|
||||
## Updating the website
|
||||
|
||||
Push the website changes you made earlier to the OpenSSL website repo. When
|
||||
you do this, the website will get updated and a script to flush the Akamai
|
||||
CDN cache will be run. You can look at things on www-origin.openssl.org;
|
||||
the CDN-hosted www.openssl.org should only be a few minutes delayed.
|
||||
|
||||
# Post-publishing tasks
|
||||
|
||||
## Check the website
|
||||
|
||||
Verify that the release notes, which are built from the CHANGES.md file
|
||||
in the release, have been updated. This is done automatically by the
|
||||
commit-hook, but if you see a problem, try the following steps on
|
||||
`dev.openssl.org`:
|
||||
|
||||
cd /var/www/openssl
|
||||
sudo -u openssl -H make relupd
|
||||
sudo -u openssl -H ./bin/purge-one-hour
|
||||
|
||||
Wait for a while for the Akamai flush to work (normally within a few minutes).
|
||||
Have a look at the website and news announcement at:
|
||||
|
||||
- <https://www.openssl.org/>
|
||||
- <https://www.openssl.org/news/>
|
||||
|
||||
Check the download page has updated properly:
|
||||
|
||||
- <https://www.openssl.org/source/>
|
||||
|
||||
Check the notes look sensible at:
|
||||
|
||||
- <https://www.openssl.org/news/newslog.html>
|
||||
|
||||
Also check the notes here:
|
||||
|
||||
- <https://www.openssl.org/news/openssl-1.0.2-notes.html>
|
||||
- <https://www.openssl.org/news/openssl-1.1.0-notes.html>
|
||||
- <https://www.openssl.org/news/openssl-1.1.1-notes.html>
|
||||
|
||||
## Send the announcement mail
|
||||
|
||||
Send out the announcements. Generic release announcement messages will be
|
||||
created automatically by the build script and the commands you need to use
|
||||
to send them were displayed when you executed do-release.pl above.
|
||||
These should normally be sent from the openssl account. These are sent to
|
||||
openssl-users, openssl-project, and openssl-announce.
|
||||
|
||||
If do-release.pl was used with `--move` be sure to move the announcement
|
||||
text files away from the staging directory after they have been sent. This
|
||||
is done as follows (with VERSION replaced with the version of OpenSSL to
|
||||
announce):
|
||||
|
||||
sudo -u openssl \
|
||||
mutt -s "OpenSSL version VERSION published" \
|
||||
openssl-project openssl-users openssl-announce \
|
||||
< /home/openssl/dist/new/openssl-VERSION.txt.asc
|
||||
sudo -u openssl \
|
||||
mv ~openssl/dist/new/openssl-VERSION.txt.asc ~openssl/dist/old
|
||||
|
||||
## Send out the Security Advisory
|
||||
|
||||
*The secadv file mentioned in this section is the Security Advisory
|
||||
that you copied into the web repo, up in the section
|
||||
[Update the website locally](#update-the-website-locally)*
|
||||
|
||||
*This section is only applicable if this is a security release*
|
||||
|
||||
Start with signing the Security Advisory as yourself:
|
||||
|
||||
gpg --clearsign secadv_FILENAME.txt
|
||||
|
||||
Then copy the result to the temporary directory on dev.openssl.org:
|
||||
|
||||
scp secadv_FILENAME.txt.asc dev.openssl.org:/tmp
|
||||
|
||||
To finish, log in on dev.openssl.org and send the signed Security
|
||||
Advisory by email as the openssl user, and the remove it:
|
||||
|
||||
sudo -u openssl mutt -s "OpenSSL Security Advisory" \
|
||||
openssl-project openssl-users openssl-announce \
|
||||
</tmp/secadv_FILENAME.txt.asc
|
||||
rm /tmp/secadv_FILENAME.txt.asc
|
||||
|
||||
Approve the openssl-announce email. Go to
|
||||
<https://mta.openssl.org/mailman/admindb/openssl-announce>
|
||||
and approve the messages.
|
||||
|
||||
Check the mailing list messages have arrived.
|
||||
|
||||
## Unfreeze the source repository.
|
||||
|
||||
ssh openssl-git@git.openssl.org unfreeze openssl
|
||||
|
||||
## Security fixes
|
||||
|
||||
If this release includes security fixes with a CVE then you should inform
|
||||
MITRE about them. See the instructions at the top of cvepool.txt in omc.
|
||||
|
||||
Close the github advisory without pushing to github and remove the private
|
||||
github fork if there was one.
|
||||
|
||||
## Keep in touch
|
||||
|
||||
Check mailing lists over the next few hours for reports of any success or
|
||||
failure. If necessary fix these and in the worst case make another
|
||||
release.
|
||||
|
||||
8
README
8
README
|
|
@ -1,3 +1,7 @@
|
|||
A collection of tools useful in OpenSSL development.
|
||||
A collection of tools and instructions useful in OpenSSL development.
|
||||
|
||||
Each tool is in its own subdirectory and has its own README
|
||||
Each set of tools is in its own subdirectory and has its own manuals
|
||||
and READMEs.
|
||||
|
||||
More generic instructions are in this top directory, called
|
||||
HOWTO-something.md
|
||||
|
|
|
|||
Loading…
Reference in New Issue