Skip to content

Document complete release version updates #2748

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
JamesNK merged 1 commit into from
Jul 22, 2026
Merged

Document complete release version updates #2748

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
71 changes: 44 additions & 27 deletions doc/release_process.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,44 +9,61 @@ release that the new release depends on.

## Releasing a new version of grpc-dotnet (every 6 weeks)

- Before cutting the release branch
- If needed, on the master branch update the `Grpc.Tools` and `Grpc.Core` dependency versions in [Directory.Packages.props](https://github.com/grpc/grpc-dotnet/blob/master/Directory.Packages.props)
to the latest pre-release of `Grpc.Tools` or `Grpc.Core` (that was released as part of the grpc/grpc release process)
- Make sure that any patches/bugfixes from the last released branch have been applied to the master branch as well.
1. Before cutting the release branch:
- If needed, on the master branch update the `Grpc.Tools` and `Grpc.Core` dependency versions in [Directory.Packages.props](https://github.com/grpc/grpc-dotnet/blob/master/Directory.Packages.props)
to the latest applicable pre-release or stable version produced by the grpc/grpc release process.
- Make sure that any patches or bug fixes from the last released branch have been applied to the master branch as well.
- Confirm that all four version values listed below are set to the current development version on master. Do not assume that cutting a branch updates them.

- Cut the release branch from master branch (the branch format is `v2.25.x`, `v2.26.x`, ...).
This release branch will be used for all subsequent pre-releases and patch releases within the same release cycle.
2. Cut the release branch from the master branch (the branch format is `v2.25.x`, `v2.26.x`, ...).
This release branch will be used for all subsequent pre-releases and patch releases within the same release cycle.

- On the release branch, replace the `-dev` suffix by `-pre1` under `<GrpcDotnetVersion>` version release number in [version.props](https://github.com/grpc/grpc-dotnet/blob/master/build/version.props)
to prepare for building the pre-release nugets.
- You'll also need to update `CurrentVersion` field in `Grpc.Core.Api`'s [VersionInfo.cs](https://github.com/grpc/grpc-dotnet/blob/6bbbf3627797ad8f787eced10b0e548cfd9ece15/src/Grpc.Core.Api/VersionInfo.cs#L44) to match the version number (otherwise tests will fail).
- Also check that the minor version number matches the branch name.
3. On the release branch, set **all four** version values for the pre-release. For example, when preparing `2.80.0-pre1`:

- Build the signed nuget packages and push them to nuget.org (internal process). **These are the pre-release packages.**
| File | Value | Pre-release example |
| --- | --- | --- |
| [build/version.props](https://github.com/grpc/grpc-dotnet/blob/master/build/version.props) | `GrpcDotnetVersion` | `2.80.0-pre1` |
| [build/version.props](https://github.com/grpc/grpc-dotnet/blob/master/build/version.props) | `GrpcDotnetAssemblyFileVersion` | `2.80.0.0` |
| [src/Grpc.Core.Api/VersionInfo.cs](https://github.com/grpc/grpc-dotnet/blob/master/src/Grpc.Core.Api/VersionInfo.cs) | `CurrentVersion` | `2.80.0-pre1` |
| [src/Grpc.Core.Api/VersionInfo.cs](https://github.com/grpc/grpc-dotnet/blob/master/src/Grpc.Core.Api/VersionInfo.cs) | `CurrentAssemblyFileVersion` | `2.80.0.0` |

- Create a new release and tag in https://github.com/grpc/grpc-dotnet/releases (by creating the tag from the current release branch).
Mark the release as "pre-release" in the github UI. Fill in the release notes.
- The package and current versions include the pre-release suffix. The file versions are numeric and do not include it.
- `GrpcDotnetAssemblyFileVersion` and `CurrentAssemblyFileVersion` must match and must not be lower than the file version of the previous stable release.
- `GrpcDotnetAssemblyVersion` and `CurrentAssemblyVersion` remain `2.0.0.0`; verify that they still match.
- Check that the release version matches the release branch name.

- Wait for the stable release of `Grpc.Tools` from the `grpc/grpc` repository (as scheduled by the release schedule), keep checking the issue tracker for problems with the new grpc-dotnet pre-release packages.
If problems are discovered and they need to be fixed, the release manager might choose to release more pre-releases (`-pre2`, `-pre3`, ...) before deciding to release as stable.

- **Make sure at least 7 days have elapsed since the last pre-release before proceeding with the stable release**, to give users enough time to test the prerelease nugets and discover potential issues. This is to decrease the likelyhood of pushing a bad stable release.
4. Build the signed NuGet packages (internal process). **These are the pre-release packages.**
Before pushing them, inspect the package metadata and a DLL from each produced package that contains assemblies, and confirm that:
- The NuGet package version and DLL `ProductVersion` match `GrpcDotnetVersion`.
- The DLL `FileVersion` matches `GrpcDotnetAssemblyFileVersion`.
- `Grpc.Core.Api.VersionInfo` reports the values set above.
Push the packages to nuget.org only after these checks pass.

- Once stable version of `Grpc.Tools` is pushed, remove `-pre1` suffix of the `<GrpcDotnetVersion>` version release number in [version.props](https://github.com/grpc/grpc-dotnet/blob/master/build/version.props) to prepare for the stable release.

- Update `CurrentVersion` field in `Grpc.Core.Api`'s [VersionInfo.cs](https://github.com/grpc/grpc-dotnet/blob/6bbbf3627797ad8f787eced10b0e548cfd9ece15/src/Grpc.Core.Api/VersionInfo.cs#L44) to match the version number (otherwise tests will fail).
5. Create a new release and tag in https://github.com/grpc/grpc-dotnet/releases (by creating the tag from the current release branch).
Mark the release as "pre-release" in the GitHub UI. Fill in the release notes.

- Build the signed nuget packages and push them to nuget.org (internal process). **These are the stable grpc-dotnet packages.**
6. Wait for the stable release of `Grpc.Tools` from the `grpc/grpc` repository (as scheduled by the release schedule), and keep checking the issue tracker for problems with the new grpc-dotnet pre-release packages.
If problems are discovered and they need to be fixed, the release manager might choose to release more pre-releases (`-pre2`, `-pre3`, ...) before deciding to release as stable. For each additional pre-release, update both `GrpcDotnetVersion` and `CurrentVersion` to the new suffix and repeat the package checks in step 4.

- Create a new release and tag in https://github.com/grpc/grpc-dotnet/releases (by creating the tag from the current release branch).
This is the stable release. Fill in the release notes and list changes since the previous _stable_ version.
7. **Make sure at least 7 days have elapsed since the last pre-release before proceeding with the stable release**, to give users enough time to test the pre-release NuGet packages and discover potential issues. This decreases the likelihood of pushing a bad stable release.

8. Once the stable version of `Grpc.Tools` is pushed, prepare the stable release:
- Update the `Grpc.Tools` dependency in `Directory.Packages.props` if it does not already reference the stable version.
- Remove the pre-release suffix from both `GrpcDotnetVersion` and `CurrentVersion`.
- Verify again that `GrpcDotnetAssemblyFileVersion` and `CurrentAssemblyFileVersion` contain the numeric stable version and match each other. Do not leave either value at an older release.
- Verify that `GrpcDotnetAssemblyVersion` and `CurrentAssemblyVersion` remain `2.0.0.0` and match each other.

9. Build the signed NuGet packages (internal process). **These are the stable grpc-dotnet packages.**
Repeat all artifact checks in step 4 against the stable version, then push the packages to nuget.org.

10. Create a new release and tag in https://github.com/grpc/grpc-dotnet/releases (by creating the tag from the current release branch).
This is the stable release. Fill in the release notes and list changes since the previous _stable_ version.

### After the release

On the master branch, increase the version number to indicate start of a new release cycle (v2.25.0-dev become v2.26.0-dev)
On the master branch, increase the version number to indicate the start of a new release cycle (`2.25.0-dev` becomes `2.26.0-dev`). Update all four values from step 3: use the new `-dev` version for `GrpcDotnetVersion` and `CurrentVersion`, and the corresponding numeric version for `GrpcDotnetAssemblyFileVersion` and `CurrentAssemblyFileVersion`.

## Process for patch releases

- Patch releases are created from an existing release branch by bumping the patch component of the version number
- When bugfixes are merged to a release branch, make sure they are synced into the master branch as well (otherwise the fixes might be missing in the next release cycle)
1. Create patch releases from an existing release branch by bumping the patch component in all four values from step 3. Use the patch's pre-release or stable version for `GrpcDotnetVersion` and `CurrentVersion`, and its numeric version for `GrpcDotnetAssemblyFileVersion` and `CurrentAssemblyFileVersion`. Repeat the artifact checks in step 4.
2. When bug fixes are merged to a release branch, make sure they are synced into the master branch as well; otherwise, the fixes might be missing from the next release cycle.
Loading