1 How to Create a Release of GRPC Java (for Maintainers Only) 2 =============================================================== 3 4 Build Environments 5 ------------------ 6 We deploy GRPC to Maven Central under the following systems: 7 - Ubuntu 14.04 with Docker 13.03.0 that runs CentOS 6.9 8 - Windows 7 64-bit with Visual Studio 9 - Mac OS X 10.12.6 10 11 Other systems may also work, but we haven't verified them. 12 13 Prerequisites 14 ------------- 15 16 ### Set Up OSSRH Account 17 18 If you haven't deployed artifacts to Maven Central before, you need to setup 19 your OSSRH (OSS Repository Hosting) account. 20 - Follow the instructions on [this 21 page](http://central.sonatype.org/pages/ossrh-guide.html) to set up an 22 account with OSSRH. 23 - You only need to create the account, not set up a new project 24 - Contact a gRPC maintainer to add your account after you have created it. 25 26 Common Variables 27 ---------------- 28 Many of the following commands expect release-specific variables to be set. Set 29 them before continuing, and set them again when resuming. 30 31 ```bash 32 $ MAJOR=1 MINOR=7 PATCH=0 # Set appropriately for new release 33 $ VERSION_FILES=( 34 build.gradle 35 android/build.gradle 36 android-interop-testing/app/build.gradle 37 core/src/main/java/io/grpc/internal/GrpcUtil.java 38 cronet/build.gradle 39 documentation/android-channel-builder.md 40 examples/build.gradle 41 examples/pom.xml 42 examples/android/clientcache/app/build.gradle 43 examples/android/helloworld/app/build.gradle 44 examples/android/routeguide/app/build.gradle 45 examples/example-kotlin/build.gradle 46 examples/example-kotlin/android/helloworld/app/build.gradle 47 ) 48 ``` 49 50 51 Branching the Release 52 --------------------- 53 The first step in the release process is to create a release branch and bump 54 the SNAPSHOT version. Our release branches follow the naming 55 convention of `v<major>.<minor>.x`, while the tags include the patch version 56 `v<major>.<minor>.<patch>`. For example, the same branch `v1.7.x` 57 would be used to create all `v1.7` tags (e.g. `v1.7.0`, `v1.7.1`). 58 59 1. For `master`, change root build files to the next minor snapshot (e.g. 60 ``1.8.0-SNAPSHOT``). 61 62 ```bash 63 $ git checkout -b bump-version master 64 # Change version to next minor (and keep -SNAPSHOT) 65 $ sed -i 's/[0-9]\+\.[0-9]\+\.[0-9]\+\(.*CURRENT_GRPC_VERSION\)/'$MAJOR.$((MINOR+1)).0'\1/' \ 66 "${VERSION_FILES[@]}" 67 $ sed -i s/$MAJOR.$MINOR.$PATCH/$MAJOR.$((MINOR+1)).0/ \ 68 compiler/src/test{,Lite,Nano}/golden/Test{,Deprecated}Service.java.txt 69 $ ./gradlew build 70 $ git commit -a -m "Start $MAJOR.$((MINOR+1)).0 development cycle" 71 ``` 72 2. Go through PR review and submit. 73 3. Create the release branch starting just before your commit and push it to GitHub: 74 75 ```bash 76 $ git fetch upstream 77 $ git checkout -b v$MAJOR.$MINOR.x \ 78 $(git log --pretty=format:%H --grep "^Start $MAJOR.$((MINOR+1)).0 development cycle$" upstream/master)^ 79 $ git push upstream v$MAJOR.$MINOR.x 80 ``` 81 4. Go to [Travis CI settings](https://travis-ci.org/grpc/grpc-java/settings) and 82 add a _Cron Job_: 83 * Branch: `v$MAJOR.$MINOR.x` 84 * Interval: `weekly` 85 * Options: `Do not run if there has been a build in the last 24h` 86 * Click _Add_ button 87 5. Continue with Google-internal steps at go/grpc/java/releasing. 88 6. Create a milestone for the next release. 89 7. Move items out of the release milestone that didn't make the cut. Issues that 90 may be backported should stay in the release milestone. Treat issues with the 91 'release blocker' label with special care. 92 93 Tagging the Release 94 ------------------- 95 96 1. Verify there are no open issues in the release milestone. Open issues should 97 either be deferred or resolved and the fix backported. 98 2. For vMajor.Minor.x branch, change `README.md` to refer to the next release 99 version. _Also_ update the version numbers for protoc if the protobuf library 100 version was updated since the last release. 101 102 ```bash 103 $ git checkout v$MAJOR.$MINOR.x 104 $ git pull upstream v$MAJOR.$MINOR.x 105 $ git checkout -b release 106 # Bump documented versions. Don't forget protobuf version 107 $ ${EDITOR:-nano -w} README.md 108 $ git commit -a -m "Update README to reference $MAJOR.$MINOR.$PATCH" 109 ``` 110 3. Change root build files to remove "-SNAPSHOT" for the next release version 111 (e.g. `0.7.0`). Commit the result and make a tag: 112 113 ```bash 114 # Change version to remove -SNAPSHOT 115 $ sed -i 's/-SNAPSHOT\(.*CURRENT_GRPC_VERSION\)/\1/' "${VERSION_FILES[@]}" 116 $ sed -i s/-SNAPSHOT// compiler/src/test{,Lite,Nano}/golden/TestService.java.txt 117 $ ./gradlew build 118 $ git commit -a -m "Bump version to $MAJOR.$MINOR.$PATCH" 119 $ git tag -a v$MAJOR.$MINOR.$PATCH -m "Version $MAJOR.$MINOR.$PATCH" 120 ``` 121 4. Change root build files to the next snapshot version (e.g. `0.7.1-SNAPSHOT`). 122 Commit the result: 123 124 ```bash 125 # Change version to next patch and add -SNAPSHOT 126 $ sed -i 's/[0-9]\+\.[0-9]\+\.[0-9]\+\(.*CURRENT_GRPC_VERSION\)/'$MAJOR.$MINOR.$((PATCH+1))-SNAPSHOT'\1/' \ 127 "${VERSION_FILES[@]}" 128 $ sed -i s/$MAJOR.$MINOR.$PATCH/$MAJOR.$MINOR.$((PATCH+1))-SNAPSHOT/ compiler/src/test{,Lite,Nano}/golden/TestService.java.txt 129 $ ./gradlew build 130 $ git commit -a -m "Bump version to $MAJOR.$MINOR.$((PATCH+1))-SNAPSHOT" 131 ``` 132 5. Go through PR review and push the release tag and updated release branch to 133 GitHub: 134 135 ```bash 136 $ git checkout v$MAJOR.$MINOR.x 137 $ git merge --ff-only release 138 $ git push upstream v$MAJOR.$MINOR.x 139 $ git push upstream v$MAJOR.$MINOR.$PATCH 140 ``` 141 6. Close the release milestone. 142 143 Build Artifacts 144 --------------- 145 146 Trigger build as described in "Auto releasing using kokoro" at 147 go/grpc/java/releasing. 148 149 It runs three jobs on Kokoro, one on each platform. See their scripts: 150 `linux_artifacts.sh`, `windows.bat`, and `unix.sh` (called directly for OS X; 151 called within the Docker environment on Linux). The mvn-artifacts/ outputs of 152 each script is combined into a single folder and then processed by 153 `upload_artifacts.sh`, which signs the files and uploads to Sonatype. 154 155 Releasing on Maven Central 156 -------------------------- 157 158 Once all of the artifacts have been pushed to the staging repository, the 159 repository should have been closed by `upload_artifacts.sh`. Closing triggers 160 several sanity checks on the repository. If this completes successfully, the 161 repository can then be `released`, which will begin the process of pushing the 162 new artifacts to Maven Central (the staging repository will be destroyed in the 163 process). You can see the complete process for releasing to Maven Central on the 164 [OSSRH site](http://central.sonatype.org/pages/releasing-the-deployment.html). 165 166 Build interop container image 167 ----------------------------- 168 169 We have containers for each release to detect compatibility regressions with old 170 releases. Generate one for the new release by following the 171 [GCR image generation instructions](https://github.com/grpc/grpc/blob/master/tools/interop_matrix/README.md#step-by-step-instructions-for-adding-a-gcr-image-for-a-new-release-for-compatibility-test). 172 173 Update README.md 174 ---------------- 175 After waiting ~1 day and verifying that the release appears on [Maven 176 Central](http://mvnrepository.com/), cherry-pick the commit that updated the 177 README into the master branch and go through review process. 178 179 ``` 180 $ git checkout -b bump-readme master 181 $ git cherry-pick v$MAJOR.$MINOR.$PATCH^ 182 ``` 183 184 Update version referenced by tutorials 185 -------------------------------------- 186 187 Update the `grpc_java_release_tag` in 188 [\_data/config.yml](https://github.com/grpc/grpc.github.io/blob/master/_data/config.yml) 189 of the grpc.github.io repository. 190 191 Notify the Community 192 -------------------- 193 Finally, document and publicize the release. 194 195 1. Add [Release Notes](https://github.com/grpc/grpc-java/releases) for the new tag. 196 The description should include any major fixes or features since the last release. 197 You may choose to add links to bugs, PRs, or commits if appropriate. 198 2. Post a release announcement to [grpc-io](https://groups.google.com/forum/#!forum/grpc-io) 199 (`grpc-io (a] googlegroups.com`). The title should be something that clearly identifies 200 the release (e.g.`GRPC-Java <tag> Released`). 201 1. Check if JCenter has picked up the new release (https://jcenter.bintray.com/io/grpc/) 202 and include its availability in the release announcement email. JCenter should mirror 203 everything on Maven Central, but users have reported delays. 204 205 Update Hosted Javadoc 206 --------------------- 207 208 Now we need to update gh-pages with the new Javadoc: 209 210 ```bash 211 git checkout gh-pages 212 rm -r javadoc/ 213 wget -O grpc-all-javadoc.jar "http://search.maven.org/remotecontent?filepath=io/grpc/grpc-all/$MAJOR.$MINOR.$PATCH/grpc-all-$MAJOR.$MINOR.$PATCH-javadoc.jar" 214 unzip -d javadoc grpc-all-javadoc.jar 215 patch -p1 < ga.patch 216 rm grpc-all-javadoc.jar 217 rm -r javadoc/META-INF/ 218 git add -A javadoc 219 git commit -m "Javadoc for $MAJOR.$MINOR.$PATCH" 220 ``` 221 222 Push gh-pages to the main repository and verify the current version is [live 223 on grpc.io](https://grpc.io/grpc-java/javadoc/). 224
