release/README.md - platform/external/conscrypt - Git at Google

 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 publish
    ```
 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 Windows OpenJDK Release

 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
    ```
 1. Build the code and upload it to the staging repository noted previously.
    ```bash
    $ gradlew conscrypt-openjdk:build
    $ gradlew conscrypt-openjdk:publish -Dorg.gradle.parallel=false -PrepositoryId=<repository-id>
    ```

 ### 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 build.x86
    $ ninja
    $ cd ../build.arm
    $ ninja
    ```
 1. Build the code and upload it to the staging repository noted previously.
    ```bash
    $ ./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.
 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:publish -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:publish -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`).
	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 publish
	```
	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 Windows OpenJDK Release

	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
	```
	1. Build the code and upload it to the staging repository noted previously.
	```bash
	$ gradlew conscrypt-openjdk:build
	$ gradlew conscrypt-openjdk:publish -Dorg.gradle.parallel=false -PrepositoryId=<repository-id>
	```

	### 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 build.x86
	$ ninja
	$ cd ../build.arm
	$ ninja
	```
	1. Build the code and upload it to the staging repository noted previously.
	```bash
	$ ./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.
	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:publish -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:publish -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`).