NSS/Release Management

This article describes the release process for NSS on the example of version 3.26. There are additional commands in the helper script, for doing releases like 3.27.1 or 3.27.1.2 We do two-digit releases whenever we have new features. We do three-digit releases if we must fix a stable branch. We reserve four-digit release numbers to scenarios, where 3.27.1 and 3.27.2 have been released, an important branch (e.g. ESR) still uses 3.27.1 and we can't upgraded to 3.27.2, but it requires an important backported fix. In that case we'd use numbers 3.27.1.1 3.27.1.2 etc.

Prepare the NSS repo

1. clone it
   1. $ hg clone https://hg.mozilla.org/projects/nss
   2. or reuse your local tree and run

      $ hg pull -u

2. Ensure you're on the correct branch, and that you don't have anything locally applied. We usually release from the "default" branch.

   $ hg summ

3. Check that there haven't been any unexpected commits by someone else.
   1. Either have a brief look at https://hg.mozilla.org/projects/nss
   2. or check the log

      $ hg log or $ hg glog

Communication

1. (We usually declare the tree as frozen prior to release, and usually we have created a beta tag a couple of days ago, and there shouldn't have been any commits after the last beta tag.)
2. Also, we usually discuss on the nss-dev list when we freeze nspr/nss.Someone should have sent a note to the list, announcing that a new NSS release is being worked on, and that the NSS tree is frozen.
3. Please send email to the "nss-dev" list saying "The NSS trunk is open for 3.27 development" after finishing the process.
4. After the release is done:
   1. Please send email to nss-dev, saying that the NSS release has been uploaded to FTP/S3.
   2. Ask for the list of changes in the release, and ask who will send the announcement.
   3. Send the announcement to the dev-tech-crypto mailing list https://lists.mozilla.org/listinfo/dev-tech-crypto

Verify correctness

Look at the diff between the previous released version, and the latest snapshot. Verify that the changes to *.def files are clean, meaning, nobody has accidentally added new symbols to old version definitions, and any additions have been added with the correct new NSS version number.

$ hg diff -r NSS_3_25_RTM -r default | lsdiff |grep \.def$

If the above reports that any *.def files changed, inspect those changes. Mistakes must be fixed before a release.

Prepare the release

1. Ensure the required NSPR version has been updated
   1. Edit file automation/release/nspr-version.txt and set it to the minimum NSPR version that is required for this NSS release.
2. Remove beta tags

   $ cd nss

   This doesn't remove " Beta" strings.

   $ python automation/release/nss-release-helper.py remove_beta

   $ hg diff

   There should be differences in, lib/nss/nss.h, lib/softoken/softkver.h, lib/util/nssutil.h

3. Verify that
   1. _VERSION definition was changed to have the Beta string removed
   2. _VMINOR was changed if this is a minor release
   3. the _BETA definition has been changed to PR_FALSE
4. Commit the version numbers.

   $ hg commit -m "Set version numbers to 3.26 final"

5. Tag the version
   1. We start release candidate tags with RC0.
   2. When ready for RTM, let's do an RTM tag.

   $ hg tag NSS_3_26_RTM

6. Push the changes

   $ hg outgoing

   $ hg push

Prepare repo for next version

1. Increment the version number (to 3.27 in this example) and set the beta flag again.
   1. $ python automation/release/nss-release-helper.py set_beta
   2. $ python automation/release/nss-release-helper.py set_version_to_minor_release 3 27
2. Push changes
   1. $ hg commit -m "Set version numbers to 3.27 Beta"
   2. $ hg outgoing
   3. $ hg push

Create the NSS release archive

1. Make sure you have a stage directory next to the NSS dir.

   $ mkdir stage

2. Go to the NSS dir

   $ cd /your/path/to/nss

3. Let 4.12 be the required NSPR version
4. Make sure that the NSPR release archive file is contained in your stage directory. (Download it, if you don't have it.)
5. Run the following command to create two release archive files (nss-3.26.tar.gz and nss-3.26-with-nspr-4.12.tar.gz) and two files SHA1SUMS and SHA256SUMS in /your/path/to/stage/NSS_3_26_RTM/src/.

   $ python automation/release/nss-release-helper.py create_nss_release_archive 3.26 NSS_3_26_RTM 4.12 ../stage

Some additional check one may want to perform

This section is only for the paranoid, only in case you want to double-check that the created file is correct.

1. Extract the archive
2. Check that all files inside the directory use the following two prefix dirs:

   nss-3.26/nss/

   nss-3.26/nspr/

3. Check that file nss-3.26/nss/.hg_archival.txt mentions tag: NSS_3_26_RTM
4. You could double-check that the three version number files have all _BETA flags set to PR_FALSE and no version string line _VERSION contains Beta.
5. Remove the extracted directory, to ensure you won't upload the individual files.

Upload release to public ftp/amazon s3.

When running the following command ensure that you use the directory name NSS_3_26_RTM twice, both in source and in destination.

$ cd /your/path/to/stage
$ find NSS_3_26_RTM

expected output:

NSS_3_26_RTM/
NSS_3_26_RTM/src
NSS_3_26_RTM/src/nss-3.26.tar.gz
NSS_3_26_RTM/src/nss-3.26-with-nspr-4.12.tar.gz
NSS_3_26_RTM/src/SHA256SUMS
NSS_3_26_RTM/src/SHA1SUMS

1. Check that there's no NSS_3_26_RTM directory at https://ftp.mozilla.org/pub/security/nss/releases/.
2. Ensure you have aws command installed.
3. more infos on aws
4. Upload the release

   $ aws s3 cp NSS_3_26_RTM s3://net-mozaws-prod-delivery-contrib/pub/security/nss/releases/NSS_3_26_RTM --recursive

5. Check https://ftp.mozilla.org/pub/security/nss/releases/ (can be delayed!)
6. Check upload:

   $ aws s3 ls s3://net-mozaws-prod-delivery-contrib/pub/security/nss/releases/

   $ aws s3 ls s3://net-mozaws-prod-delivery-contrib/pub/security/nss/releases/NSS_3_26_RTM/

   $ aws s3 ls s3://net-mozaws-prod-delivery-contrib/pub/security/nss/releases/NSS_3_26_RTM/src/

Upgrading mozilla-central

1. Someone should approve the upgrade.
2. For the upgrade task, we have docs https://developer.mozilla.org/en/docs/Updating_NSPR_or_NSS_in_mozilla-central Go to a mozilla-inbound checkout and run the following.

   $ python client.py update_nss NSS_3_26_RTM

   $ hg commit -m "Bug 1216283, land NSS_3_26_RTM, UPGRADE_NSS_RELEASE, r=the-reviewer-name"

   $ hg push

3. If we must land into branches, like aurora or beta, we must get approvals, etc. Note that we don't do patches for branch landing. We use a placeholder attachment

with the command to be executed. The reason is, that the state of those dependency files might be different between branches (where we upgrade or remove newlines as necessary, to trigger full rebuilds). By using the upgrade script, this is handled automatically.