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/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   ```
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/ 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   ```
1325. 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   ```
1416. Close the release milestone.
142
143Build Artifacts
144---------------
145
146Trigger build as described in "Auto releasing using kokoro" at
147go/grpc/java/releasing.
148
149It 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;
151called within the Docker environment on Linux). The mvn-artifacts/ outputs of
152each script is combined into a single folder and then processed by
153`upload_artifacts.sh`, which signs the files and uploads to Sonatype.
154
155Releasing on Maven Central
156--------------------------
157
158Once all of the artifacts have been pushed to the staging repository, the
159repository should have been closed by `upload_artifacts.sh`. Closing triggers
160several sanity checks on the repository. If this completes successfully, the
161repository can then be `released`, which will begin the process of pushing the
162new artifacts to Maven Central (the staging repository will be destroyed in the
163process). 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
166Build interop container image
167-----------------------------
168
169We have containers for each release to detect compatibility regressions with old
170releases. 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
173Update README.md
174----------------
175After waiting ~1 day and verifying that the release appears on [Maven
176Central](http://mvnrepository.com/), cherry-pick the commit that updated the
177README 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
184Update version referenced by tutorials
185--------------------------------------
186
187Update the `grpc_java_release_tag` in
188[\_data/config.yml](https://github.com/grpc/grpc.github.io/blob/master/_data/config.yml)
189of the grpc.github.io repository.
190
191Notify the Community
192--------------------
193Finally, document and publicize the release.
194
1951. 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.
1982. Post a release announcement to [grpc-io](https://groups.google.com/forum/#!forum/grpc-io)
199   (`grpc-io@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
205Update Hosted Javadoc
206---------------------
207
208Now we need to update gh-pages with the new Javadoc:
209
210```bash
211git checkout gh-pages
212rm -r javadoc/
213wget -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"
214unzip -d javadoc grpc-all-javadoc.jar
215patch -p1 < ga.patch
216rm grpc-all-javadoc.jar
217rm -r javadoc/META-INF/
218git add -A javadoc
219git commit -m "Javadoc for $MAJOR.$MINOR.$PATCH"
220```
221
222Push gh-pages to the main repository and verify the current version is [live
223on grpc.io](https://grpc.io/grpc-java/javadoc/).
224