Skip to content

Add instructions in the release process for additional sanity checks reg backporting #13180

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
kannanjgithub merged 3 commits into from
Nov 11, 2026
Merged

Add instructions in the release process for additional sanity checks reg backporting #13180

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
17958c4
Add additional sanity checks in the instructions regarding backporting
kannanjgithub Nov 9, 2026
650fbae
amend
kannanjgithub Nov 9, 2026
43054a2
Use 1. throughout for numbered items, since github markdown rendering…
kannanjgithub Nov 11, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
62 changes: 37 additions & 25 deletions RELEASING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ would be used to create all `v1.7` tags (e.g. `v1.7.0`, `v1.7.1`).
for issues that won't make the cut. Check if any of them can be
closed. Be aware of the issues with the [TODO:release blocker][] label.
Consider reaching out to the assignee for the status update.
2. For `master`, change root build files to the next minor snapshot (e.g.
1. For `master`, change root build files to the next minor snapshot (e.g.
``1.8.0-SNAPSHOT``).

```bash
Expand All @@ -59,22 +59,22 @@ would be used to create all `v1.7` tags (e.g. `v1.7.0`, `v1.7.1`).
./gradlew build
git commit -a -m "Start $MAJOR.$((MINOR+1)).0 development cycle"
```
3. Go through PR review and submit.
4. Create the release branch starting just before your commit and push it to GitHub:
1. Go through PR review and submit.
1. Create the release branch starting just before your commit and push it to GitHub:

```bash
git fetch upstream
git checkout -b v$MAJOR.$MINOR.x \
$(git log --pretty=format:%H --grep "^Start $MAJOR.$((MINOR+1)).0 development cycle" upstream/master)^
git push upstream v$MAJOR.$MINOR.x
```
5. Continue with Google-internal steps at go/grpc-java/releasing, but stop
1. Continue with Google-internal steps at go/grpc-java/releasing, but stop
before `Auto releasing using kokoro`.
6. Create a milestone for the next release.
7. Move items out of the release milestone that didn't make the cut. Issues that
1. Create a milestone for the next release.
1. Move items out of the release milestone that didn't make the cut. Issues that
may be backported should stay in the release milestone. Treat issues with the
'release blocker' label with special care.
8. Begin compiling release notes. This produces a starting point:
1. Begin compiling release notes. This produces a starting point:

```bash
echo "## gRPC Java $MAJOR.$MINOR.0 Release Notes" && echo && \
Expand All @@ -90,12 +90,23 @@ Tagging the Release
-------------------

1. Verify there are no open issues in the release milestone. Open issues should
either be deferred or resolved and the fix backported. Verify there are no
[TODO:release blocker][] nor [TODO:backport][] issues (open or closed), or
that they are tracking an issue for a different branch.
2. Ensure that the Google-internal steps
either be deferred or resolved and the fix backported, to atleast 2 most recent
branches as a rule of thumb. Verify there are no [TODO:release blocker][] nor
[TODO:backport][] issues (open or closed), or that they are tracking an issue for
a different branch. Before removing the `TODO:backport` label double-check to make
sure that there has been no missed backport of the issue in the latest branch cut
either due to
1. Mistyping the latest minor version branch to backport it to OR
1. Concurrent branching activities: There's a time window there where you can lose a
backport where the branch didn't exist. One engineer might be making a branch cut and
concurrently another engineer might be making a fix to the master branch and backporting
it to only the most recent minor version branch before the branch cut currently being made.
1. Keep a tab over the commits made on master since the branch cut, to check if any commits
standout or look suspicious that it should be backported, and check with the PR author if
necessary.
1. Ensure that the Google-internal steps
at go/grpc-java/releasing#before-tagging-a-release are completed.
3. For vMajor.Minor.x branch, change `README.md` to refer to the next release
1. For vMajor.Minor.x branch, change `README.md` to refer to the next release
version. _Also_ update the version numbers for protoc if the protobuf library
version was updated since the last release.

Expand All @@ -110,7 +121,7 @@ Tagging the Release

git commit -a -m "Update README etc to reference $MAJOR.$MINOR.$PATCH"
```
4. Change root build files to remove "-SNAPSHOT" for the next release version
1. Change root build files to remove "-SNAPSHOT" for the next release version
(e.g. `0.7.0`). Commit the result and make a tag:

```bash
Expand All @@ -121,7 +132,7 @@ Tagging the Release
git commit -a -m "Bump version to $MAJOR.$MINOR.$PATCH"
git tag -a v$MAJOR.$MINOR.$PATCH -m "Version $MAJOR.$MINOR.$PATCH"
```
5. Change root build files to the next snapshot version (e.g. `0.7.1-SNAPSHOT`).
1. Change root build files to the next snapshot version (e.g. `0.7.1-SNAPSHOT`).
Commit the result:

```bash
Expand All @@ -135,7 +146,7 @@ Tagging the Release
git push -u origin release-v$MAJOR.$MINOR.$PATCH
```
Raise a PR and set the base branch of the PR to v$MAJOR.$MINOR.x of the upstream grpc-java repo.
6. Go through PR review and push the release tag and updated release branch to
1. Go through PR review and push the release tag and updated release branch to
GitHub (DO NOT click the merge button on the GitHub page):

```bash
Expand All @@ -144,25 +155,25 @@ Tagging the Release
git push upstream v$MAJOR.$MINOR.x
git push upstream v$MAJOR.$MINOR.$PATCH
```
7. Close the release milestone.
1. Close the release milestone.

8. Trigger build as described in "Auto releasing using kokoro" at
1. Trigger build as described in "Auto releasing using kokoro" at
go/grpc-java/releasing.

It runs three jobs on Kokoro, one on each platform. See their scripts:
`linux_artifacts.sh`, `windows.bat`, and `macos.sh`. The mvn-artifacts/
outputs of each script is combined into a single folder and then processed
by `upload_artifacts.sh`, which signs the files and uploads to Sonatype.

9. Once all of the artifacts have been pushed to the staging repository, the
1. Once all of the artifacts have been pushed to the staging repository, the
repository should have been closed by `upload_artifacts.sh`. Closing triggers
several sanity checks on the repository. If this completes successfully, the
repository can then be `released`, which will begin the process of pushing
the new artifacts to Maven Central (the staging repository will be destroyed
in the process). You can see the complete process for releasing to Maven
Central on the [OSSRH site](https://central.sonatype.org/publish/publish-portal-ossrh-staging-api/#deploying).

10. We have containers for each release to detect compatibility regressions with
1. We have containers for each release to detect compatibility regressions with
old releases. Generate one for the new release by following the [GCR image
generation instructions][gcr-image]. Summary:
```bash
Expand All @@ -182,9 +193,9 @@ Tagging the Release

# Create a PR with the `release notes: no` label and run ad-hoc test against your PR
```
[gcr-image]: 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
[gcr-image]: 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

11. Update gh-pages with the new Javadoc. Generally the file is on repo1
1. Update gh-pages with the new Javadoc. Generally the file is on repo1
15 minutes after publishing:

```bash
Expand All @@ -203,16 +214,16 @@ Tagging the Release

Verify the current version is [live on grpc.io](https://grpc.io/grpc-java/javadoc/).

12. Add [Release Notes](https://github.com/grpc/grpc-java/releases) for the new tag.
1. Add [Release Notes](https://github.com/grpc/grpc-java/releases) for the new tag.
*Make sure that any backports are reflected in the release notes.*

13. Notify the Community. Post a release announcement to
1. Notify the Community. Post a release announcement to
[grpc-io](https://groups.google.com/forum/#!forum/grpc-io)
(`grpc-io@googlegroups.com`) with the title `gRPC-Java v$MAJOR.$MINOR.$PATCH
Released`. The email content should link to the GitHub release notes and
include a copy of them.

14. Update README.md. Cherry-pick the commit that updated the README.md into the
1. Update README.md. Cherry-pick the commit that updated the README.md into the
master branch.

```bash
Expand All @@ -223,7 +234,7 @@ Tagging the Release

Create a PR and go through the review process

15. Update version referenced by tutorials. Update `params.grpc_vers.java` in
1. Update version referenced by tutorials. Update `params.grpc_vers.java` in
[config.yaml](https://github.com/grpc/grpc.io/blob/master/config.yaml) of

@sauravzg sauravzg Nov 9, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: the internal markdown supports marking everything as 1. in an ordered list and the number magically works on rendering. Might be useful to see if gh markdown supports something like that as well.

@kannanjgithub kannanjgithub Nov 11, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done.

the grpc.io repository. Create a PR and go through the review process.

Expand Down Expand Up @@ -254,3 +265,4 @@ When happy with the dependency upgrades, update the versions in `MODULE.bazel`,
Upgrade the `uses:` for actions in `.github/workflows` to newer versions. Make
sure to see what changed in each new major version, but it is most often just
requiring a newer Node.js version.

Loading