Skip to content

doc(release): update release docs with BCR instructions #16329

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

Open
scotthart wants to merge 1 commit into
base: main
Choose a base branch
from
+105 −35
Open

doc(release): update release docs with BCR instructions #16329

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
140 changes: 105 additions & 35 deletions release/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,34 +10,6 @@ project that need to create a new release. We expect the reader to be familiar
the project itself, [git][git-docs], [GitHub][github-guides], and
[semantic versioning](https://semver.org).

## 0. Update googleapis and Publish to BCR

First, ensure that our release includes a `googleapis` commit that adheres to
our [update policy][googleapis-sha-update-policy]. This generally means aiming
for a commit that is 5-7 days old. You may need to run the
`external/googleapis/renovate.sh` script to select the desired commit. By
default, it uses the latest commit, but you can specify an older one using the
`COMMIT` and `COMMIT_DATE` variables.

Once the `googleapis` commit has been updated in our repository and the change
is merged, run the `release/publish-bcr.sh` script using the same selected
COMMIT. This script will create a Pull Request in the `googleapis/googleapis`
repository to publish our new version to the Bazel Central Registry. You will
need to provide the version number and the corresponding `googleapis` commit SHA
to the script. Oversee the generated PR and ensure it is merged before
proceeding with the release.

```bash
release/publish-bcr.sh --ref "${COMMIT}" --bcr_organization "${your_gh_id}"
```

Note that either `--bcr_organization` or `--bcr_folder` are necessary in order
for the script to use your fork of `bazel-central-registry`. Pushes to the
original `bazelbuild/bazel-central-registry` are not allowed.

You can find more information about running the script in
[its readme](https://github.com/googleapis/googleapis/blob/e1b12be90da62015f0bea9026d217f0abc32cafe/.bcr/README.md)

## 1. Preparing for a release

To create a new release you need to perform some maintenance tasks, these are
Expand Down Expand Up @@ -188,9 +160,8 @@ Review the new release in the GitHub web UI (the link to the pre-release will be
output from the `release.sh` script that was run in the previous step). If
everything looks OK:

1. Uncheck the pre-release checkbox.
1. Check the latest release checkbox.
1. Click the update release button.
1. Change the "Release label" from "Pre-release" to "Latest".
1. Click the "Update release" button.

## 4. Check the published reference docs

Expand Down Expand Up @@ -231,7 +202,107 @@ Please note that we use more strict settings for release branches than for
- Turn on the `Restrict who can push to matching branches`. Only Google team
members should be pushing to release branches.

## 6. Push the release to Microsoft vcpkg
## 6. Update the google_cloud_cpp BCR module

[PR#9676](https://github.com/bazelbuild/bazel-central-registry/pull/9676) is a
good example of the changes you will need to make.

*NOTE*: Be sure to add the comment `@bazel-io skip_check unstable_url` to the
PR.

### a. Get to your clone of bazel-central-registry

#### Create a fork of https://github.com/bazelbuild/bazel-central-registry.git

Clone the fork

```shell
git clone git@github.com:<username>/bazel-central-registry.git
```

#### Sync the `main` branch in your fork to the upstream version

```shell
cd bazel-central-registry
git pull upstream main
```

### b. Make a PR for the version update

#### Save the old and new versions as an environment variables

```shell
OLD_VERSION=... # e.g. v2.12.0
VERSION=... # e.g. v2.13.0
Comment on lines +235 to +236

@gemini-code-assist gemini-code-assist Bot Aug 6, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

medium

In the Bazel Central Registry, module versions do not include the v prefix (e.g., they are 2.13.0 instead of v2.13.0). If the v prefix is included in the VERSION variable, the directory creation (modules/google_cloud_cpp/${VERSION}) and other commands will use the incorrect path. Please define these variables without the v prefix.

Suggested change
OLD_VERSION=... # e.g. v2.12.0
VERSION=... # e.g. v2.13.0
OLD_VERSION=... # e.g. 2.12.0
VERSION=... # e.g. 2.13.0

```

#### Create a feature branch.

```shell
git checkout -b google-cloud-cpp-update-to-${VERSION}
```

#### Copy the files from the previous version directory to the new

```shell
mkdir modules/google_cloud_cpp/${VERSION}
cp -r modules/google_cloud_cpp/${OLD_VERSION}/* modules/google_cloud_cpp/${VERSION}
```

#### Overwrite the the MODULE.bazel file with MODULE.bazel file from the release

@gemini-code-assist gemini-code-assist Bot Aug 6, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

medium

There is a duplicate word "the" in this heading.

Suggested change
#### Overwrite the the MODULE.bazel file with MODULE.bazel file from the release
#### Overwrite the MODULE.bazel file with MODULE.bazel file from the release


```shell
curl https://raw.githubusercontent.com/googleapis/google-cloud-cpp/refs/tags/v${VERSION}/MODULE.bazel > modules/google_cloud_cpp/${VERSION}/MODULE.bazel
```

#### Update the "versions" section of modules/google_cloud_cpp/metadata.json to add the new version

```json
"versions": [
"3.6.0",
"3.7.0",
"3.8.0"
]
```

#### Update the modules/google_cloud_cpp/3.8.0/source.json

@gemini-code-assist gemini-code-assist Bot Aug 6, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

medium

To make the instructions consistent and generic, use ${VERSION} in the heading instead of the hardcoded version 3.8.0.

Suggested change
#### Update the modules/google_cloud_cpp/3.8.0/source.json
#### Update the modules/google_cloud_cpp/${VERSION}/source.json


Compute new base64 sha256 checksum for the tar.gz file with the following
command:

```shell
curl -fSsL https://github.com/googleapis/google-cloud-cpp/archive/v${VERSION}.tar.gz | sha256sum | awk '{print $1}' | xxd -r -p | base64

@gemini-code-assist gemini-code-assist Bot Aug 6, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

medium

The command computes the base64 SHA256 checksum but does not assign it to the SHA256 environment variable. As a result, the subsequent sed command will replace the integrity field with an empty hash. Assign the output of the command to the SHA256 variable.

Suggested change
curl -fSsL https://github.com/googleapis/google-cloud-cpp/archive/v${VERSION}.tar.gz | sha256sum | awk '{print $1}' | xxd -r -p | base64
SHA256=$(curl -fSsL https://github.com/googleapis/google-cloud-cpp/archive/v${VERSION}.tar.gz | sha256sum | awk '{print $1}' | xxd -r -p | base64)

```

- Update the "integrity" field with the new base64 encoded sha256 checksum.

```shell
sed -i "s#\"integrity\": \"sha256-.*=\"#\"integrity\": \"sha256-${SHA256}\"#" modules/google_cloud_cpp/${VERSION}/source.json
```

- Update the "url" and "strip_prefix" fields with the new version manually.

#### Commit these changes

```shell
git add modules/google_cloud_cpp
git commit -m"feat: add google_cloud_cpp@${VERSION}"
```

#### Push the changes to the remote repo

```shell
git push
```

#### Create the PR

https://github.com/bazelbuild/bazel-central-registry/pulls

*NOTE*: Be sure to add the comment `@bazel-io skip_check unstable_url` to the
PR.

## 7. \[BLOCKED on [vcpkg#47167](https://github.com/microsoft/vcpkg/issues/47167)\] Push the release to Microsoft vcpkg

[PR#32391] is probably a good example of the changes you will need to make.

Expand Down Expand Up @@ -356,14 +427,14 @@ and
```
</pre>

## 7. Monitor the automation on Conda
## 8. Monitor the automation on Conda

On [Conda](https://conda.io) things are mostly automated. A robot will create a
PR, similar to [PR#138]. If you want, subscribe to notifications in the
[conda feedstock repository] or just look at the PRs in that repository over the
next 24 hours.

## 8. [optional] Push the release to Conan
## 9. [optional] Push the release to Conan

The documentation has moved to the
[How-To Guide: Update Conan Package](/release/howto-update-conan-package.md).
Expand Down Expand Up @@ -448,7 +519,6 @@ ______________________________________________________________________
[git-docs]: https://git-scm.com/doc
[github-branch-settings]: https://github.com/googleapis/google-cloud-cpp/settings/branches
[github-guides]: https://guides.github.com/
[googleapis-sha-update-policy]: https://github.com/googleapis/google-cloud-cpp/blob/main/doc/adr/2024-08-13-googleapis-sha-update-policy.md
[pr#138]: https://github.com/conda-forge/google-cloud-cpp-feedstock/pull/138
[pr#15008]: https://github.com/googleapis/google-cloud-cpp/pull/15008
[pr#32391]: https://github.com/microsoft/vcpkg/pull/32391
Expand Down