1How to Create a Release of GRPC Java (for Maintainers Only) 2=============================================================== 3 4Build Environments 5------------------ 6We 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 11Other systems may also work, but we haven't verified them. 12 13Prerequisites 14------------- 15 16### Set Up OSSRH Account 17 18If you haven't deployed artifacts to Maven Central before, you need to setup 19your 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 26Common Variables 27---------------- 28Many of the following commands expect release-specific variables to be set. Set 29them 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 51Branching the Release 52--------------------- 53The first step in the release process is to create a release branch and bump 54the SNAPSHOT version. Our release branches follow the naming 55convention 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` 57would be used to create all `v1.7` tags (e.g. `v1.7.0`, `v1.7.1`). 58 591. 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 ``` 722. Go through PR review and submit. 733. 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 ``` 814. 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 875. Continue with Google-internal steps at go/grpc/java/releasing. 886. Create a milestone for the next release. 897. 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 93Tagging the Release 94------------------- 95 961. Verify there are no open issues in the release milestone. Open issues should 97 either be deferred or resolved and the fix backported. 982. 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 ``` 1103. 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/Test{,Deprecated}Service.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 ``` 1214. 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/ \ 129 compiler/src/test{,Lite,Nano}/golden/Test{,Deprecated}Service.java.txt 130 $ ./gradlew build 131 $ git commit -a -m "Bump version to $MAJOR.$MINOR.$((PATCH+1))-SNAPSHOT" 132 ``` 1335. Go through PR review and push the release tag and updated release branch to 134 GitHub: 135 136 ```bash 137 $ git checkout v$MAJOR.$MINOR.x 138 $ git merge --ff-only release 139 $ git push upstream v$MAJOR.$MINOR.x 140 $ git push upstream v$MAJOR.$MINOR.$PATCH 141 ``` 1426. Close the release milestone. 143 144Build Artifacts 145--------------- 146 147Trigger build as described in "Auto releasing using kokoro" at 148go/grpc/java/releasing. 149 150It runs three jobs on Kokoro, one on each platform. See their scripts: 151`linux_artifacts.sh`, `windows.bat`, and `unix.sh` (called directly for OS X; 152called within the Docker environment on Linux). The mvn-artifacts/ outputs of 153each script is combined into a single folder and then processed by 154`upload_artifacts.sh`, which signs the files and uploads to Sonatype. 155 156Releasing on Maven Central 157-------------------------- 158 159Once all of the artifacts have been pushed to the staging repository, the 160repository should have been closed by `upload_artifacts.sh`. Closing triggers 161several sanity checks on the repository. If this completes successfully, the 162repository can then be `released`, which will begin the process of pushing the 163new artifacts to Maven Central (the staging repository will be destroyed in the 164process). You can see the complete process for releasing to Maven Central on the 165[OSSRH site](http://central.sonatype.org/pages/releasing-the-deployment.html). 166 167Build interop container image 168----------------------------- 169 170We have containers for each release to detect compatibility regressions with old 171releases. Generate one for the new release by following the 172[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). 173 174Update README.md 175---------------- 176After waiting ~1 day and verifying that the release appears on [Maven 177Central](http://mvnrepository.com/), cherry-pick the commit that updated the 178README into the master branch and go through review process. 179 180``` 181$ git checkout -b bump-readme master 182$ git cherry-pick v$MAJOR.$MINOR.$PATCH^ 183``` 184 185Update version referenced by tutorials 186-------------------------------------- 187 188Update the `grpc_java_release_tag` in 189[\_data/config.yml](https://github.com/grpc/grpc.github.io/blob/master/_data/config.yml) 190of the grpc.github.io repository. 191 192Notify the Community 193-------------------- 194Finally, document and publicize the release. 195 1961. Add [Release Notes](https://github.com/grpc/grpc-java/releases) for the new tag. 197 The description should include any major fixes or features since the last release. 198 You may choose to add links to bugs, PRs, or commits if appropriate. 1992. Post a release announcement to [grpc-io](https://groups.google.com/forum/#!forum/grpc-io) 200 (`grpc-io@googlegroups.com`). The title should be something that clearly identifies 201 the release (e.g.`GRPC-Java <tag> Released`). 202 1. Check if JCenter has picked up the new release (https://jcenter.bintray.com/io/grpc/) 203 and include its availability in the release announcement email. JCenter should mirror 204 everything on Maven Central, but users have reported delays. 205 206Update Hosted Javadoc 207--------------------- 208 209Now we need to update gh-pages with the new Javadoc: 210 211```bash 212git checkout gh-pages 213rm -r javadoc/ 214wget -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" 215unzip -d javadoc grpc-all-javadoc.jar 216patch -p1 < ga.patch 217rm grpc-all-javadoc.jar 218rm -r javadoc/META-INF/ 219git add -A javadoc 220git commit -m "Javadoc for $MAJOR.$MINOR.$PATCH" 221``` 222 223Push gh-pages to the main repository and verify the current version is [live 224on grpc.io](https://grpc.io/grpc-java/javadoc/). 225