1How to Create a Release of Conscrypt (for Maintainers Only) 2=========================================================== 3 4Build Environments 5------------------ 6We deploy Conscrypt to Maven Central under the following systems: 7- Ubuntu 14.04 with Docker 1.6.1 that runs CentOS 6.6 8- Windows 7 64-bit 9- Mac OS X 10.7+ 10 11Other systems may also work, but we haven't verified them. 12 13BoringSSL Version 14----------------- 15 16Each build environment for a particular release *MUST* use the same version 17of BoringSSL. This is necessary in order to maintain consistency across 18platforms as well as to allow the Uber JAR to specify a single version for 19BoringSSL in its MANIFEST.MF. 20 21When deploying, it may be useful to begin with Linux (via Docker), 22taking note of the BoringSSL version used, and then deploying 23Mac and Windows with that version via: 24 25```bash 26boringssl$ git checkout <commit id> 27``` 28 29Prerequisites 30------------- 31 32### Setup OSSRH and Signing 33 34If you haven't deployed artifacts to Maven Central before, you need to setup 35your OSSRH (OSS Repository Hosting) account and signing keys. 36- Follow the instructions on [this 37 page](http://central.sonatype.org/pages/ossrh-guide.html) to set up an 38 account with OSSRH. 39 - You only need to create the account, not set up a new project 40 - Contact a Conscrypt maintainer to add your account after you have created it. 41- (For release deployment only) Install GnuPG and [generate your key 42 pair](https://www.gnupg.org/documentation/howtos.html). You'll also 43 need to [publish your public key](https://www.gnupg.org/gph/en/manual.html#AEN464) 44 to make it visible to the Sonatype servers 45 (e.g. `gpg --keyserver pgp.mit.edu --send-key <key ID>`). 46- Put your GnuPG key password and OSSRH account information in 47 `<your-home-directory>/.gradle/gradle.properties`. 48 49``` 50# You need the signing properties only if you are making release deployment 51signing.keyId=<8-character-public-key-id> 52signing.password=<key-password> 53signing.secretKeyRingFile=<your-home-directory>/.gnupg/secring.gpg 54 55ossrhUsername=<ossrh-username> 56ossrhPassword=<ossrh-password> 57checkstyle.ignoreFailures=false 58``` 59 60Tagging the Release 61---------------------- 62The first step in the release process is to create a release branch, bump 63versions, and create a tag for the release. Our release branches follow the naming 64convention of `v<major>.<minor>.x`, while the tags include the patch version 65`v<major>.<minor>.<patch>`. For example, the same branch `v1.0.x` 66would be used to create all `v1.0` tags (e.g. `v1.0.0`, `v1.0.1`). 67 681. Create the release branch and push it to GitHub: 69 70 ```bash 71 $ git checkout -b 1.0.x master 72 $ git push upstream 1.0.x 73 ``` 742. Update `master` branch to the next minor snapshot (e.g. `1.1.0-SNAPSHOT`) 75 and update references to the version in `README.md`. 76 77 ```bash 78 $ git checkout -b bump-version master 79 # Change version to next minor (and keep -SNAPSHOT) 80 $ ${EDITOR:-nano -w} build.gradle 81 # Bump documented versions. 82 $ ${EDITOR:-nano -w} README.md 83 $ ./gradlew build 84 $ git commit -a -m "Start 1.1.0 development cycle" 85 ``` 863. Go through PR review and push the master branch to GitHub: 87 88 ```bash 89 $ git checkout master 90 $ git merge --ff-only bump-version 91 $ git push upstream master 92 ``` 934. In the release branch, remove "-SNAPSHOT" for the next release version 94 (e.g. '1.0.0') and update references to the version in `README.md`. 95 Commit the result and make a tag: 96 97 ```bash 98 $ git checkout 1.0.x 99 # Change version to remove -SNAPSHOT 100 $ ${EDITOR:-nano -w} build.gradle 101 # Bump documented versions. 102 $ ${EDITOR:-nano -w} README.md 103 $ git commit -a -m "Change version to 1.0.0" 104 $ git tag -a 1.0.0 -m "Version 1.0.0" 105 ``` 1065. In the release branch, bump to the next patch snapshot version 107 (e.g. `1.0.1-SNAPSHOT`). Commit the result: 108 109 ```bash 110 # Change version to next patch and add -SNAPSHOT 111 $ ${EDITOR:-nano -w} build.gradle 112 $ ./gradlew build 113 $ git commit -a -m "Bump version to 1.0.1-SNAPSHOT" 114 ``` 1157. Go through PR review and push the release tag and updated release branch to 116 GitHub: 117 118 ```bash 119 $ git push upstream 1.0.0 120 $ git push upstream 1.0.x 121 ``` 122 123Setup Build Environment 124--------------------------- 125 126### Linux 127The deployment for Linux uses [Docker](https://www.docker.com/) running 128CentOS 6.6 in order to ensure that we have a consistent deployment environment 129on Linux. You'll first need to install Docker if not already installed on your 130system. 131 1321. From the conscrypt source directory: 133 134 ```bash 135 conscrypt$ docker build -t conscrypt-deploy . 136 ``` 1372. 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. 1473. Next, you'll need to copy your OSSRH credentials and GnuPG keys to your docker container. 148 In Docker: 149 ``` 150 # mkdir /root/.gradle 151 ``` 152 Find the container ID in your bash prompt, which is shown as `[root@<container-ID> ...]`. 153 In host: 154 ``` 155 $ docker cp ~/.gnupg <container-ID>:/root/ 156 $ docker cp ~/.gradle/gradle.properties <container-ID>:/root/.gradle/ 157 ``` 158 159 You'll also need to update `signing.secretKeyRingFile` in 160 `/root/.gradle/gradle.properties` to point to `/root/.gnupg/secring.gpg`. 161 162### Windows and Mac 163 164For Windows and Mac, see [BUILDING](BUILDING.md) for instructions for setting up the build environment. 165 166Build and Deploy 167---------------- 168We currently distribute the following OSes and architectures: 169 170| OS | x86_32 | x86_64 | 171| --- | --- | --- | 172| Linux | | X | 173| Mac | | X | 174| Windows | X | X | 175 176Deployment to Maven Central (or the snapshot repo) is a two-step process. The only 177artifact that is platform-specific is codegen, so we only need to deploy the other 178jars once. So the first deployment is for all of the artifacts from one of the selected 179OS/architectures. After that, we then deploy the codegen artifacts for the remaining 180OS/architectures. 181 182**NOTE: _Before building/deploying, be sure to switch to the appropriate branch or tag in 183the Conscrypt source directory._** 184 185### First Deployment (or SNAPSHOT) 186 187As stated above, this only needs to be done once for one of the selected OS/architectures. 188The following command will build the whole project and upload it to Maven 189Central. Parallel building [is not safe during 190uploadArchives](https://issues.gradle.org/browse/GRADLE-3420). 191 192**Linux/Mac:** 193```bash 194conscrypt$ ./gradlew build && ./gradlew -Dorg.gradle.parallel=false uploadArchives 195``` 196 197**Windows:** 198```bat 199C:\conscrypt>gradlew build && gradlew -Dorg.gradle.parallel=false uploadArchives 200 201``` 202 203If the version has the `-SNAPSHOT` suffix, the artifacts will automatically 204go to the snapshot repository. Otherwise it's a release deployment and the 205artifacts will go to a freshly created staging repository. 206 207### Deploy OpenJDK for Additional Platforms (Release Deployment Only) 208The previous step will only deploy the artifacts for the OS you run on 209it and the architecture of your JVM. For a fully fledged deployment, you will 210need to deploy for each supported OS/architecture. 211 212When deploying a Release, the first deployment will create 213[a new staging repository](https://oss.sonatype.org/#stagingRepositories). You'll need 214to look up the ID in the OSSRH UI (usually in the form of `orgconscrypt-*`). Codegen 215deployment commands should include `-PrepositoryId=<repository-id>` in order to 216ensure that the artifacts are pushed to the same staging repository. 217 218**Linux/Mac:** 219```bash 220conscrypt$ ./gradlew build && ./gradlew -Dorg.gradle.parallel=false \ 221 conscrypt-openjdk:uploadArchives -PrepositoryId=<repository-id> 222``` 223 224**Windows:** 225```bat 226C:\conscrypt>gradlew build && gradlew -Dorg.gradle.parallel=false ^ 227 conscrypt-openjdk:uploadArchives -PrepositoryId=<repository-id> 228 229``` 230 231Now finish [Releasing on Maven Central](#releasing-on-maven-central). 232 233### Deploy the Uber JAR (Release Deployment Only) 234Once all of the native JARs appear on Maven Central, you can build and deploy 235the Uber JAR that contains all of them. 236 237**Linux/Mac:** 238```bash 239conscrypt$ ./gradlew conscrypt-openjdk-uber:build \ 240 -Dorg.conscrypt.openjdk.buildUberJar=true 241 242conscrypt$ ./gradlew conscrypt-openjdk-uber:uploadArchives \ 243 -Dorg.gradle.parallel=false \ 244 -Dorg.conscrypt.openjdk.buildUberJar=true 245``` 246 247**Windows:** 248```bat 249C:\conscrypt>gradlew conscrypt-openjdk-uber:build ^ 250 -Dorg.conscrypt.openjdk.buildUberJar=true 251 252C:\conscrypt>gradlew conscrypt-openjdk-uber:uploadArchives ^ 253 -Dorg.gradle.parallel=false ^ 254 -Dorg.conscrypt.openjdk.buildUberJar=true 255 256``` 257 258This will create 259[a new staging repository](https://oss.sonatype.org/#stagingRepositories), 260so you'll need to [close and release](#releasing-on-maven-central) the 261repository via the OSSRH UI, as you did in the previous step. 262 263Releasing on Maven Central 264-------------------------- 265Once all of the artifacts have been pushed to the staging repository, the 266repository must first be `closed`, which will trigger several sanity checks 267on the repository. If this completes successfully, the repository can then 268be `released`, which will begin the process of pushing the new artifacts to 269Maven Central (the staging repository will be destroyed in the process). You can 270see the complete process for releasing to Maven Central on the [OSSRH site] 271(http://central.sonatype.org/pages/releasing-the-deployment.html). 272 273Notify the Community 274-------------------- 275Finally, document and publicize the release. 276 2771. Add [Release Notes](https://github.com/google/conscrypt/releases) for the new tag. 278 The description should include any major fixes or features since the last release. 279 You may choose to add links to bugs, PRs, or commits if appropriate. 2802. Post a release announcement to [conscrypt](https://groups.google.com/forum/#!forum/conscrypt) 281 (`conscrypt@googlegroups.com`). The title should be something that clearly identifies 282 the release (e.g.`Conscrypt <tag> Released`). 283