1 How to Create a Release of Conscrypt (for Maintainers Only) 2 =========================================================== 3 4 Build Environments 5 ------------------ 6 We 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 11 Other systems may also work, but we haven't verified them. 12 13 BoringSSL Version 14 ----------------- 15 16 Each build environment for a particular release *MUST* use the same version 17 of BoringSSL. This is necessary in order to maintain consistency across 18 platforms as well as to allow the Uber JAR to specify a single version for 19 BoringSSL in its MANIFEST.MF. 20 21 When deploying, it may be useful to begin with Linux (via Docker), 22 taking note of the BoringSSL version used, and then deploying 23 Mac and Windows with that version via: 24 25 ```bash 26 boringssl$ git checkout <commit id> 27 ``` 28 29 Prerequisites 30 ------------- 31 32 ### Setup OSSRH and Signing 33 34 If you haven't deployed artifacts to Maven Central before, you need to setup 35 your 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 51 signing.keyId=<8-character-public-key-id> 52 signing.password=<key-password> 53 signing.secretKeyRingFile=<your-home-directory>/.gnupg/secring.gpg 54 55 ossrhUsername=<ossrh-username> 56 ossrhPassword=<ossrh-password> 57 checkstyle.ignoreFailures=false 58 ``` 59 60 Tagging the Release 61 ---------------------- 62 The first step in the release process is to create a release branch, bump 63 versions, and create a tag for the release. Our release branches follow the naming 64 convention 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` 66 would be used to create all `v1.0` tags (e.g. `v1.0.0`, `v1.0.1`). 67 68 1. 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 ``` 74 2. 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 ``` 86 3. 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 ``` 93 4. 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 ``` 106 5. 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 ``` 115 7. 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 123 Setup Build Environment 124 --------------------------- 125 126 ### Linux 127 The deployment for Linux uses [Docker](https://www.docker.com/) running 128 CentOS 6.6 in order to ensure that we have a consistent deployment environment 129 on Linux. You'll first need to install Docker if not already installed on your 130 system. 131 132 1. From the conscrypt source directory: 133 134 ```bash 135 conscrypt$ docker build -t conscrypt-deploy . 136 ``` 137 2. 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. 147 3. 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 164 For Windows and Mac, see [BUILDING](BUILDING.md) for instructions for setting up the build environment. 165 166 Build and Deploy 167 ---------------- 168 We 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 176 Deployment to Maven Central (or the snapshot repo) is a two-step process. The only 177 artifact that is platform-specific is codegen, so we only need to deploy the other 178 jars once. So the first deployment is for all of the artifacts from one of the selected 179 OS/architectures. After that, we then deploy the codegen artifacts for the remaining 180 OS/architectures. 181 182 **NOTE: _Before building/deploying, be sure to switch to the appropriate branch or tag in 183 the Conscrypt source directory._** 184 185 ### First Deployment (or SNAPSHOT) 186 187 As stated above, this only needs to be done once for one of the selected OS/architectures. 188 The following command will build the whole project and upload it to Maven 189 Central. Parallel building [is not safe during 190 uploadArchives](https://issues.gradle.org/browse/GRADLE-3420). 191 192 **Linux/Mac:** 193 ```bash 194 conscrypt$ ./gradlew build && ./gradlew -Dorg.gradle.parallel=false uploadArchives 195 ``` 196 197 **Windows:** 198 ```bat 199 C:\conscrypt>gradlew build && gradlew -Dorg.gradle.parallel=false uploadArchives 200 201 ``` 202 203 If the version has the `-SNAPSHOT` suffix, the artifacts will automatically 204 go to the snapshot repository. Otherwise it's a release deployment and the 205 artifacts will go to a freshly created staging repository. 206 207 ### Deploy OpenJDK for Additional Platforms (Release Deployment Only) 208 The previous step will only deploy the artifacts for the OS you run on 209 it and the architecture of your JVM. For a fully fledged deployment, you will 210 need to deploy for each supported OS/architecture. 211 212 When deploying a Release, the first deployment will create 213 [a new staging repository](https://oss.sonatype.org/#stagingRepositories). You'll need 214 to look up the ID in the OSSRH UI (usually in the form of `orgconscrypt-*`). Codegen 215 deployment commands should include `-PrepositoryId=<repository-id>` in order to 216 ensure that the artifacts are pushed to the same staging repository. 217 218 **Linux/Mac:** 219 ```bash 220 conscrypt$ ./gradlew build && ./gradlew -Dorg.gradle.parallel=false \ 221 conscrypt-openjdk:uploadArchives -PrepositoryId=<repository-id> 222 ``` 223 224 **Windows:** 225 ```bat 226 C:\conscrypt>gradlew build && gradlew -Dorg.gradle.parallel=false ^ 227 conscrypt-openjdk:uploadArchives -PrepositoryId=<repository-id> 228 229 ``` 230 231 Now finish [Releasing on Maven Central](#releasing-on-maven-central). 232 233 ### Deploy the Uber JAR (Release Deployment Only) 234 Once all of the native JARs appear on Maven Central, you can build and deploy 235 the Uber JAR that contains all of them. 236 237 **Linux/Mac:** 238 ```bash 239 conscrypt$ ./gradlew conscrypt-openjdk-uber:build \ 240 -Dorg.conscrypt.openjdk.buildUberJar=true 241 242 conscrypt$ ./gradlew conscrypt-openjdk-uber:uploadArchives \ 243 -Dorg.gradle.parallel=false \ 244 -Dorg.conscrypt.openjdk.buildUberJar=true 245 ``` 246 247 **Windows:** 248 ```bat 249 C:\conscrypt>gradlew conscrypt-openjdk-uber:build ^ 250 -Dorg.conscrypt.openjdk.buildUberJar=true 251 252 C:\conscrypt>gradlew conscrypt-openjdk-uber:uploadArchives ^ 253 -Dorg.gradle.parallel=false ^ 254 -Dorg.conscrypt.openjdk.buildUberJar=true 255 256 ``` 257 258 This will create 259 [a new staging repository](https://oss.sonatype.org/#stagingRepositories), 260 so you'll need to [close and release](#releasing-on-maven-central) the 261 repository via the OSSRH UI, as you did in the previous step. 262 263 Releasing on Maven Central 264 -------------------------- 265 Once all of the artifacts have been pushed to the staging repository, the 266 repository must first be `closed`, which will trigger several sanity checks 267 on the repository. If this completes successfully, the repository can then 268 be `released`, which will begin the process of pushing the new artifacts to 269 Maven Central (the staging repository will be destroyed in the process). You can 270 see the complete process for releasing to Maven Central on the [OSSRH site] 271 (http://central.sonatype.org/pages/releasing-the-deployment.html). 272 273 Notify the Community 274 -------------------- 275 Finally, document and publicize the release. 276 277 1. 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. 280 2. Post a release announcement to [conscrypt](https://groups.google.com/forum/#!forum/conscrypt) 281 (`conscrypt (a] googlegroups.com`). The title should be something that clearly identifies 282 the release (e.g.`Conscrypt <tag> Released`). 283
