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:
<!-- TODO(flooey): Expand and link these, there's probably more -->
* Linux: [Docker](https://www.docker.com/), [Android SDK](https://developer.android.com/studio/index.html)
* 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](http://central.sonatype.org/pages/ossrh-guide.html) 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](https://www.gnupg.org/documentation/howtos.html).
- [Publish your public key](https://www.gnupg.org/gph/en/manual.html#AEN464)
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:
```bash
$ 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.
```bash
$ 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.
```bash
$ git checkout 1.0.x
$ git cherry-pick <revision>
```
### Tag the release
```bash
# 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.
```bash
$ git push upstream 1.0.x
$ git push upstream 1.0.0
```
### Build the Linux OpenJDK Release
The deployment for Linux uses [Docker](https://www.docker.com/) running
CentOS 6.6 in order to ensure that we have a consistent deployment environment
on Linux.
1. From the conscrypt source directory:
```bash
$ docker build -t conscrypt-deploy release
```
1. Start a Docker container that has the deploy environment set up for you. The
Conscrypt source is cloned into `/conscrypt`.
```bash
$ 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.
1. 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.
1. Create the initial build
```bash
$ git checkout 1.0.x
$ ./gradlew conscrypt-openjdk:build
$ ./gradlew -Dorg.gradle.parallel=false uploadArchives
```
1. Note the BoringSSL commit used for this build.
```bash
$ cd /usr/src/boringssl
$ git log -n 1
```
1. 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 Mac and Windows OpenJDK Releases
See [BUILDING](../BUILDING.md) for instructions for setting up the build environment.
1. Ensure BoringSSL is synced to the same revision as for the Linux build.
```bash
$ git checkout <revision>
$ cd build64
$ ninja
# For Windows only
$ cd ..\build32
$ ninja
```
1. Build the code and upload it to the staging repository noted previously.
```bash
$ ./gradlew conscrypt-openjdk:build
$ ./gradlew conscrypt-openjdk:uploadArchives -Dorg.gradle.parallel=false -PrepositoryId=<repository-id>
```
(Omit the `./` for the Windows build.)
### 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.
1. Click the `close` button at the top of the staging repo list.
1. 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](http://search.maven.org).
### 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.
```bash
$ ./gradlew conscrypt-android:build
$ ./gradlew conscrypt-android:uploadArchives -Dorg.gradle.parallel=false
```
1. 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.
```bash
# 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:uploadArchives -Dorg.gradle.parallel=false -Dorg.conscrypt.openjdk.buildUberJar=true
```
1. Visit the OSSRH site and close and release the repository.
### Notify the Community
Finally, document and publicize the release.
1. Add [Release Notes](https://github.com/google/conscrypt/releases) 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](https://groups.google.com/forum/#!forum/conscrypt)
(`conscrypt@googlegroups.com`). The title should be something that clearly identifies
the release (e.g.`Conscrypt <tag> Released`).