How to Create a Conscrypt Release

One-Time Setup

These steps need to be performed once by each person doing releases.

Platforms

Conscrypt is built on Linux, Mac, and Windows, so ensure you have access to machines running all three. The 1.0.0 release was made with the following configuration:

• Ubuntu 14.04
• MacOS Sierra (10.12)
• Windows Server 2016

Software

The following software is necessary and may not be installed by default:

• Linux: Docker, Android SDK
• MacOS: Java SDK
• Windows: MSVC, git, NASM, Java

Setup OSSRH and GPG

If you haven't deployed artifacts to Maven Central before, you need to setup your OSSRH (OSS Repository Hosting) account and signing keys.

• Follow the instructions on this page to set up an account with OSSRH.
  • You only need to create the account, not set up a new project
  • Contact a Conscrypt maintainer to add your account after you have created it.
• Install GnuPG and generate your key pair.
• Publish your public key to make it visible to the Sonatype servers (e.g. gpg --keyserver pgp.mit.edu --send-key <key ID>).

Get the signing certificates

Contact an existing Conscrypt maintainer to get the keystore containing the code signing certificate.

Set up gradle.properties

Add your OSSRH credentials, GPG key information, and the code signing keystore details to $HOME/.gradle/gradle.properties.

signing.keyId=<8-character-public-key-id>
signing.password=<key-password>
signing.secretKeyRingFile=<your-home-directory>/.gnupg/secring.gpg

signingKeystore=<path-to-keystore>
signingPassword=<keystore-password>

ossrhUsername=<ossrh-username>
ossrhPassword=<ossrh-password>
checkstyle.ignoreFailures=false

Once Per Release Series Setup

These steps need to be performed once per X.Y release series.

Create the release branch

We use a branch named <major>.<minor>.x for all releases in a series.

Create the branch and push it to GitHub:

$ git checkout -b 1.0.x master
$ git push upstream 1.0.x

Set the branch protection settings

In the GitHub UI, go to Settings -> Branches and mark the new branch as protected, with administrators included and restrict pushes to administrators.

Update the master version

Update the master branch's version to the next minor snapshot.

$ git checkout -b bump-version master
# Change version in build.gradle to X.Y+1-SNAPSHOT
$ git commit -a -m 'Start X.Y+1 development cycle'
# Push to GitHub and get reviewed like normal

Making a New Release

Cherry-pick changes from the master branch (optional)

Cherry-pick any desired master changes since the branch was created.

$ git checkout 1.0.x
$ git cherry-pick <revision>

Tag the release

# Change version in build.gradle to this version's number
$ git commit -a -m 'Preparing version 1.0.0'
$ git tag -a 1.0.0 -m 'Version 1.0.0'

Push to GitHub

Push both the branch and the new tag to GitHub.

$ git push upstream 1.0.x
$ git push upstream 1.0.0

Build the Linux OpenJDK Release

The deployment for Linux uses Docker running CentOS 6.6 in order to ensure that we have a consistent deployment environment on Linux.

1. From the conscrypt source directory:

   $ docker build -t conscrypt-deploy release
   

2. Start a Docker container that has the deploy environment set up for you. The Conscrypt source is cloned into /conscrypt.

   $ docker run -it --rm=true conscrypt-deploy
   

   Note that the container will be deleted after you exit. Any changes you have made (e.g., copied configuration files) will be lost. If you want to keep the container, remove --rm=true from the command line.

3. Copy your OSSRH credentials and GnuPG keys to your docker container. In Docker:

   # mkdir /root/.gradle
   

   Find the container ID in your bash prompt, which is shown as [root@<container-ID> ...]. In host:

   $ docker cp ~/.gnupg <container-ID>:/root/
   $ docker cp ~/.gradle/gradle.properties <container-ID>:/root/.gradle/
   $ docker cp <path to cert keystore> <container-ID>:/root/certkeystore
   

   You'll also need to update signing.secretKeyRingFile and signingKeystore in /root/.gradle/gradle.properties to point to /root/.gnupg/secring.gpg and /root/certkeystore, respectively.

4. Create the initial build

   $ git checkout 1.0.x
   $ ./gradlew conscrypt-openjdk:build
   $ ./gradlew -Dorg.gradle.parallel=false publish
   

5. Note the BoringSSL commit used for this build.

   $ cd /usr/src/boringssl
   $ git log -n 1
   

6. Go to the OSSRH UI and note the ID of the new staging repository. It should be in the form of orgconscrypt-NNNN.

Build the Windows OpenJDK Release

See BUILDING for instructions for setting up the build environment.

1. Ensure BoringSSL is synced to the same revision as for the Linux build.

   $ git checkout <revision>
   $ cd build64
   $ ninja
   

2. Build the code and upload it to the staging repository noted previously.

   $ gradlew conscrypt-openjdk:build
   $ gradlew conscrypt-openjdk:publish -Dorg.gradle.parallel=false -PrepositoryId=<repository-id>
   

Build the Mac and Windows OpenJDK Releases

See BUILDING for instructions for setting up the build environment.

1. Ensure BoringSSL is synced to the same revision as for the Linux build.

   $ git checkout <revision>
   $ cd build.x86
   $ ninja
   $ cd ../build.arm
   $ ninja
   

2. Build the code and upload it to the staging repository noted previously.

   $ ./gradlew conscrypt-openjdk:build
   $ ./gradlew conscrypt-openjdk:publish -Dorg.gradle.parallel=false -PrepositoryId=<repository-id>
   

Close and Release the Staging Repository

1. Navigate to the staging repository, open the contents, and ensure there are jars for each supported build environment: linux-x86_64, osx-x86_64, windows-x86, and windows-x86_64.
2. Click the close button at the top of the staging repo list.
3. After the automated checks are done, click the release button at the top of the staging repo list.

You can see the complete process for releasing to Maven Central on the [OSSRH site] (http://central.sonatype.org/pages/releasing-the-deployment.html).

It will take several hours for the jars to show up on Maven Central.

Build the Android Release

The Android build is not yet integrated into the Docker container, so on any machine with the Android SDK installed, do the following:

1. Build the code.

   $ ./gradlew conscrypt-android:build
   $ ./gradlew conscrypt-android:publish -Dorg.gradle.parallel=false
   

2. Visit the OSSRH site and close and release the repository.

Build the Uber Jar

Once the platform-specific jars have shown up on Maven Central, return to the Docker container and build the Uber jar.

1. Build the code.

   # If you left the container, reattach to it
   $ docker container attach {CONTAINER_ID}
   $ ./gradlew conscrypt-openjdk-uber:build -Dorg.conscrypt.openjdk.buildUberJar=true
   $ ./gradlew conscrypt-openjdk-uber:publish -Dorg.gradle.parallel=false -Dorg.conscrypt.openjdk.buildUberJar=true
   

2. Visit the OSSRH site and close and release the repository.

Notify the Community

Finally, document and publicize the release.

1. Add Release Notes for the new tag. The description should include any major fixes or features since the last release. You may choose to add links to bugs, PRs, or commits if appropriate.
2. Post a release announcement to conscrypt (conscrypt@googlegroups.com). The title should be something that clearly identifies the release (e.g.Conscrypt <tag> Released).