1How to Create a Conscrypt Release 2==================================== 3 4One-Time Setup 5-------------- 6 7These steps need to be performed once by each person doing releases. 8 9### Platforms 10 11Conscrypt is built on Linux, Mac, and Windows, so ensure you have access to machines 12running all three. The 1.0.0 release was made with the following configuration: 13 14* Ubuntu 14.04 15* MacOS Sierra (10.12) 16* Windows Server 2016 17 18### Software 19 20The following software is necessary and may not be installed by default: 21 22<!-- TODO(flooey): Expand and link these, there's probably more --> 23* Linux: [Docker](https://www.docker.com/), [Android SDK](https://developer.android.com/studio/index.html) 24* MacOS: Java SDK 25* Windows: MSVC, git, NASM, Java 26 27### Setup OSSRH and GPG 28 29If you haven't deployed artifacts to Maven Central before, you need to setup 30your OSSRH (OSS Repository Hosting) account and signing keys. 31- Follow the instructions on [this 32 page](http://central.sonatype.org/pages/ossrh-guide.html) to set up an 33 account with OSSRH. 34 - You only need to create the account, not set up a new project 35 - Contact a Conscrypt maintainer to add your account after you have created it. 36- Install GnuPG and [generate your key 37 pair](https://www.gnupg.org/documentation/howtos.html). 38- [Publish your public key](https://www.gnupg.org/gph/en/manual.html#AEN464) 39 to make it visible to the Sonatype servers 40 (e.g. `gpg --keyserver pgp.mit.edu --send-key <key ID>`). 41 42### Get the signing certificates 43 44Contact an existing Conscrypt maintainer to get the keystore containing the 45code signing certificate. 46 47### Set up gradle.properties 48 49Add your OSSRH credentials, GPG key information, and the code signing keystore details 50to `$HOME/.gradle/gradle.properties`. 51 52``` 53signing.keyId=<8-character-public-key-id> 54signing.password=<key-password> 55signing.secretKeyRingFile=<your-home-directory>/.gnupg/secring.gpg 56 57signingKeystore=<path-to-keystore> 58signingPassword=<keystore-password> 59 60ossrhUsername=<ossrh-username> 61ossrhPassword=<ossrh-password> 62checkstyle.ignoreFailures=false 63``` 64 65Once Per Release Series Setup 66----------------------------- 67 68These steps need to be performed once per `X.Y` release series. 69 70### Create the release branch 71 72We use a branch named `<major>.<minor>.x` for all releases in a series. 73 74Create the branch and push it to GitHub: 75 76```bash 77$ git checkout -b 1.0.x master 78$ git push upstream 1.0.x 79``` 80 81### Set the branch protection settings 82 83In the GitHub UI, go to Settings -> Branches and mark the new branch as 84protected, with administrators included and restrict pushes to administrators. 85 86### Update the master version 87 88Update the master branch's version to the next minor snapshot. 89 90```bash 91$ git checkout -b bump-version master 92# Change version in build.gradle to X.Y+1-SNAPSHOT 93$ git commit -a -m 'Start X.Y+1 development cycle' 94# Push to GitHub and get reviewed like normal 95``` 96 97Making a New Release 98-------------------- 99 100### Cherry-pick changes from the master branch (optional) 101 102Cherry-pick any desired master changes since the branch was created. 103 104```bash 105$ git checkout 1.0.x 106$ git cherry-pick <revision> 107``` 108 109### Tag the release 110 111```bash 112# Change version in build.gradle to this version's number 113$ git commit -a -m 'Preparing version 1.0.0' 114$ git tag -a 1.0.0 -m 'Version 1.0.0' 115``` 116 117### Push to GitHub 118 119Push both the branch and the new tag to GitHub. 120 121```bash 122$ git push upstream 1.0.x 123$ git push upstream 1.0.0 124``` 125 126### Build the Linux OpenJDK Release 127 128The deployment for Linux uses [Docker](https://www.docker.com/) running 129CentOS 6.6 in order to ensure that we have a consistent deployment environment 130on Linux. 131 1321. From the conscrypt source directory: 133 134 ```bash 135 $ docker build -t conscrypt-deploy release 136 ``` 1371. Start a Docker container that has the deploy environment set up for you. The 138 Conscrypt source is cloned into `/conscrypt`. 139 140 ```bash 141 $ docker run -it --rm=true conscrypt-deploy 142 ``` 143 144 Note that the container will be deleted after you exit. Any changes you have 145 made (e.g., copied configuration files) will be lost. If you want to keep the 146 container, remove `--rm=true` from the command line. 1471. Copy your OSSRH credentials and GnuPG keys to your docker container. In Docker: 148 ``` 149 # mkdir /root/.gradle 150 ``` 151 Find the container ID in your bash prompt, which is shown as `[root@<container-ID> ...]`. 152 In host: 153 ``` 154 $ docker cp ~/.gnupg <container-ID>:/root/ 155 $ docker cp ~/.gradle/gradle.properties <container-ID>:/root/.gradle/ 156 $ docker cp <path to cert keystore> <container-ID>:/root/certkeystore 157 ``` 158 159 You'll also need to update `signing.secretKeyRingFile` and `signingKeystore` in 160 `/root/.gradle/gradle.properties` to point to `/root/.gnupg/secring.gpg` and 161 `/root/certkeystore`, respectively. 1621. Create the initial build 163 ```bash 164 $ git checkout 1.0.x 165 $ ./gradlew conscrypt-openjdk:build 166 $ ./gradlew -Dorg.gradle.parallel=false publish 167 ``` 1681. Note the BoringSSL commit used for this build. 169 ```bash 170 $ cd /usr/src/boringssl 171 $ git log -n 1 172 ``` 1731. Go to the OSSRH UI and note the ID of the new staging repository. It should be in the 174 form of `orgconscrypt-NNNN`. 175 176### Build the Windows OpenJDK Release 177 178See [BUILDING](../BUILDING.md) for instructions for setting up the build environment. 179 1801. Ensure BoringSSL is synced to the same revision as for the Linux build. 181 ```bash 182 $ git checkout <revision> 183 $ cd build64 184 $ ninja 185 ``` 1861. Build the code and upload it to the staging repository noted previously. 187 ```bash 188 $ gradlew conscrypt-openjdk:build 189 $ gradlew conscrypt-openjdk:publish -Dorg.gradle.parallel=false -PrepositoryId=<repository-id> 190 ``` 191 192### Build the Mac and Windows OpenJDK Releases 193 194See [BUILDING](../BUILDING.md) for instructions for setting up the build environment. 195 1961. Ensure BoringSSL is synced to the same revision as for the Linux build. 197 ```bash 198 $ git checkout <revision> 199 $ cd build.x86 200 $ ninja 201 $ cd ../build.arm 202 $ ninja 203 ``` 2041. Build the code and upload it to the staging repository noted previously. 205 ```bash 206 $ ./gradlew conscrypt-openjdk:build 207 $ ./gradlew conscrypt-openjdk:publish -Dorg.gradle.parallel=false -PrepositoryId=<repository-id> 208 ``` 209 210### Close and Release the Staging Repository 211 2121. Navigate to the staging repository, open the contents, and ensure there are jars for 213 each supported build environment: linux-x86_64, osx-x86_64, windows-x86, and windows-x86_64. 2141. Click the `close` button at the top of the staging repo list. 2151. After the automated checks are done, click the `release` button at the top of the staging repo list. 216 217You can see the complete process for releasing to Maven Central on the [OSSRH site] 218(http://central.sonatype.org/pages/releasing-the-deployment.html). 219 220It will take several hours for the jars to show up on [Maven Central](http://search.maven.org). 221 222### Build the Android Release 223 224The Android build is not yet integrated into the Docker container, so on any machine with 225the Android SDK installed, do the following: 226 2271. Build the code. 228 ```bash 229 $ ./gradlew conscrypt-android:build 230 $ ./gradlew conscrypt-android:publish -Dorg.gradle.parallel=false 231 ``` 2321. Visit the OSSRH site and close and release the repository. 233 234### Build the Uber Jar 235 236Once the platform-specific jars have shown up on Maven Central, return to the Docker container 237and build the Uber jar. 238 2391. Build the code. 240 ```bash 241 # If you left the container, reattach to it 242 $ docker container attach {CONTAINER_ID} 243 $ ./gradlew conscrypt-openjdk-uber:build -Dorg.conscrypt.openjdk.buildUberJar=true 244 $ ./gradlew conscrypt-openjdk-uber:publish -Dorg.gradle.parallel=false -Dorg.conscrypt.openjdk.buildUberJar=true 245 ``` 2461. Visit the OSSRH site and close and release the repository. 247 248### Notify the Community 249 250Finally, document and publicize the release. 251 2521. Add [Release Notes](https://github.com/google/conscrypt/releases) for the new tag. 253 The description should include any major fixes or features since the last release. 254 You may choose to add links to bugs, PRs, or commits if appropriate. 2552. Post a release announcement to [conscrypt](https://groups.google.com/forum/#!forum/conscrypt) 256 (`[email protected]`). The title should be something that clearly identifies 257 the release (e.g.`Conscrypt <tag> Released`). 258