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 7 8- Windows 7 64-bit with Visual Studio 9- Mac OS X 10.14.6 10 11Other systems may also work, but we haven't verified them. 12 13Common Variables 14---------------- 15Many of the following commands expect release-specific variables to be set. Set 16them before continuing, and set them again when resuming. 17 18```bash 19$ MAJOR=1 MINOR=7 PATCH=0 # Set appropriately for new release 20$ VERSION_FILES=( 21 build.gradle 22 core/src/main/java/io/grpc/internal/GrpcUtil.java 23 examples/build.gradle 24 examples/pom.xml 25 examples/android/clientcache/app/build.gradle 26 examples/android/helloworld/app/build.gradle 27 examples/android/routeguide/app/build.gradle 28 examples/android/strictmode/app/build.gradle 29 examples/example-*/build.gradle 30 examples/example-*/pom.xml 31 ) 32``` 33 34 35Branching the Release 36--------------------- 37The first step in the release process is to create a release branch and bump 38the SNAPSHOT version. Our release branches follow the naming 39convention of `v<major>.<minor>.x`, while the tags include the patch version 40`v<major>.<minor>.<patch>`. For example, the same branch `v1.7.x` 41would be used to create all `v1.7` tags (e.g. `v1.7.0`, `v1.7.1`). 42 431. Review the issues in the current release [milestone](https://github.com/grpc/grpc-java/milestones) 44 for issues that won't make the cut. Check if any of them can be 45 closed. Be aware of the issues with the [TODO:release blocker][] label. 46 Consider reaching out to the assignee for the status update. 472. For `master`, change root build files to the next minor snapshot (e.g. 48 ``1.8.0-SNAPSHOT``). 49 50 ```bash 51 $ git checkout -b bump-version master 52 # Change version to next minor (and keep -SNAPSHOT) 53 $ sed -i 's/[0-9]\+\.[0-9]\+\.[0-9]\+\(.*CURRENT_GRPC_VERSION\)/'$MAJOR.$((MINOR+1)).0'\1/' \ 54 "${VERSION_FILES[@]}" 55 $ sed -i s/$MAJOR.$MINOR.$PATCH/$MAJOR.$((MINOR+1)).0/ \ 56 compiler/src/test{,Lite}/golden/Test{,Deprecated}Service.java.txt 57 $ ./gradlew build 58 $ git commit -a -m "Start $MAJOR.$((MINOR+1)).0 development cycle" 59 ``` 603. Go through PR review and submit. 614. Create the release branch starting just before your commit and push it to GitHub: 62 63 ```bash 64 $ git fetch upstream 65 $ git checkout -b v$MAJOR.$MINOR.x \ 66 $(git log --pretty=format:%H --grep "^Start $MAJOR.$((MINOR+1)).0 development cycle$" upstream/master)^ 67 $ git push upstream v$MAJOR.$MINOR.x 68 ``` 695. Continue with Google-internal steps at go/grpc/java/releasing, but stop 70 before `Auto releasing using kokoro`. 716. Create a milestone for the next release. 727. Move items out of the release milestone that didn't make the cut. Issues that 73 may be backported should stay in the release milestone. Treat issues with the 74 'release blocker' label with special care. 758. Begin compiling release notes. This produces a starting point: 76 77 ```bash 78 $ echo "## gRPC Java $MAJOR.$MINOR.0 Release Notes" && echo && \ 79 git shortlog "$(git merge-base upstream/v$MAJOR.$((MINOR-1)).x upstream/v$MAJOR.$MINOR.x)"..upstream/v$MAJOR.$MINOR.x | cat && \ 80 echo && echo && echo "Backported commits in previous release:" && \ 81 git log --oneline "$(git merge-base v$MAJOR.$((MINOR-1)).0 upstream/v$MAJOR.$MINOR.x)"..v$MAJOR.$((MINOR-1)).0^ 82 ``` 83 84[TODO:release blocker]: https://github.com/grpc/grpc-java/issues?q=label%3A%22TODO%3Arelease+blocker%22 85[TODO:backport]: https://github.com/grpc/grpc-java/issues?q=label%3ATODO%3Abackport 86 87Tagging the Release 88------------------- 89 901. Verify there are no open issues in the release milestone. Open issues should 91 either be deferred or resolved and the fix backported. Verify there are no 92 [TODO:release blocker][] nor [TODO:backport][] issues (open or closed), or 93 that they are tracking an issue for a different branch. 942. Ensure that Google-internal steps completed at go/grpc/java/releasing#before-tagging-a-release. 953. For vMajor.Minor.x branch, change `README.md` to refer to the next release 96 version. _Also_ update the version numbers for protoc if the protobuf library 97 version was updated since the last release. 98 99 ```bash 100 $ git checkout v$MAJOR.$MINOR.x 101 $ git pull upstream v$MAJOR.$MINOR.x 102 $ git checkout -b release-v$MAJOR.$MINOR.$PATCH 103 104 # Bump documented gRPC versions. 105 # Also update protoc version to match protobuf version in gradle/libs.versions.toml. 106 $ ${EDITOR:-nano -w} README.md 107 108 $ git commit -a -m "Update README etc to reference $MAJOR.$MINOR.$PATCH" 109 ``` 1104. 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}/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 ``` 1215. 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}/golden/Test{,Deprecated}Service.java.txt 130 $ ./gradlew build 131 $ git commit -a -m "Bump version to $MAJOR.$MINOR.$((PATCH+1))-SNAPSHOT" 132 ``` 1336. Go through PR review and push the release tag and updated release branch to 134 GitHub (DO NOT click the merge button on the GitHub page): 135 136 ```bash 137 $ git checkout v$MAJOR.$MINOR.x 138 $ git merge --ff-only release-v$MAJOR.$MINOR.$PATCH 139 $ git push upstream v$MAJOR.$MINOR.x 140 $ git push upstream v$MAJOR.$MINOR.$PATCH 141 ``` 1427. 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](https://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](https://search.maven.org/search?q=g:io.grpc), cherry-pick the commit 178that updated the README into the master branch. 179 180```bash 181$ git checkout -b bump-readme master 182$ git cherry-pick v$MAJOR.$MINOR.$PATCH^ 183$ git push --set-upstream origin bump-readme 184``` 185 186NOTE: If you add to your ~/.gitconfig the following, you don't need the 187`--set-upstream` 188 189```text 190[push] 191 autoSetupRemote = true 192``` 193 194Create a PR and go through the review process 195 196Update version referenced by tutorials 197-------------------------------------- 198 199Update `params.grpc_vers.java` in 200[config.yaml](https://github.com/grpc/grpc.io/blob/master/config.yaml) 201of the grpc.io repository. 202 203Notify the Community 204-------------------- 205Finally, document and publicize the release. 206 2071. Add [Release Notes](https://github.com/grpc/grpc-java/releases) for the new tag. 208 The description should include any major fixes or features since the last release. 209 You may choose to add links to bugs, PRs, or commits if appropriate. 2102. Post a release announcement to [grpc-io](https://groups.google.com/forum/#!forum/grpc-io) 211 (`[email protected]`). The title should be something that clearly identifies 212 the release (e.g.`GRPC-Java <tag> Released`). 213 - Note that there may have been backports to the release branch since you 214 generated the release notes. Please verify that any backports are reflected 215 in the release notes before sending them out. 216 217Update Hosted Javadoc 218--------------------- 219 220Now we need to update gh-pages with the new Javadoc: 221 222```bash 223git checkout gh-pages 224git pull --ff-only upstream gh-pages 225rm -r javadoc/ 226wget -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" 227unzip -d javadoc grpc-all-javadoc.jar 228patch -p1 < ga.patch 229rm grpc-all-javadoc.jar 230rm -r javadoc/META-INF/ 231git add -A javadoc 232git commit -m "Javadoc for $MAJOR.$MINOR.$PATCH" 233``` 234 235Push gh-pages to the main repository and verify the current version is [live 236on grpc.io](https://grpc.io/grpc-java/javadoc/). 237