1# Releasing
2
3## Determine which module to release
4
5The Go client libraries have several modules. Each module does not strictly
6correspond to a single library - they correspond to trees of directories. If a
7file needs to be released, you must release the closest ancestor module.
8
9To see all modules:
10
11```bash
12$ cat `find . -name go.mod` | grep module
13module cloud.google.com/go/pubsub
14module cloud.google.com/go/spanner
15module cloud.google.com/go
16module cloud.google.com/go/bigtable
17module cloud.google.com/go/bigquery
18module cloud.google.com/go/storage
19module cloud.google.com/go/pubsublite
20module cloud.google.com/go/firestore
21module cloud.google.com/go/logging
22module cloud.google.com/go/internal/gapicgen
23module cloud.google.com/go/internal/godocfx
24module cloud.google.com/go/internal/examples/fake
25module cloud.google.com/go/internal/examples/mock
26module cloud.google.com/go/datastore
27```
28
29The `cloud.google.com/go` is the repository root module. Each other module is
30a submodule.
31
32So, if you need to release a change in `bigtable/bttest/inmem.go`, the closest
33ancestor module is `cloud.google.com/go/bigtable` - so you should release a new
34version of the `cloud.google.com/go/bigtable` submodule.
35
36If you need to release a change in `asset/apiv1/asset_client.go`, the closest
37ancestor module is `cloud.google.com/go` - so you should release a new version
38of the `cloud.google.com/go` repository root module. Note: releasing
39`cloud.google.com/go` has no impact on any of the submodules, and vice-versa.
40They are released entirely independently.
41
42## Test failures
43
44If there are any test failures in the Kokoro build, releases are blocked until
45the failures have been resolved.
46
47## How to release
48
49### Automated Releases (`cloud.google.com/go` and submodules)
50
51We now use [release-please](https://github.com/googleapis/release-please) to
52perform automated releases for `cloud.google.com/go` and all submodules.
53
541. If there are changes that have not yet been released, a
55 [pull request](https://github.com/googleapis/google-cloud-go/pull/2971) will
56 be automatically opened by release-please
57 with a title like "chore: release X.Y.Z" (for the root module) or
58 "chore: release datastore X.Y.Z" (for the datastore submodule), where X.Y.Z
59 is the next version to be released. Find the desired pull request
60 [here](https://github.com/googleapis/google-cloud-go/pulls)
611. Check for failures in the
62 [continuous Kokoro build](http://go/google-cloud-go-continuous). If there are
63 any failures in the most recent build, address them before proceeding with
64 the release. (This applies even if the failures are in a different submodule
65 from the one being released.)
661. Review the release notes. These are automatically generated from the titles
67 of any merged commits since the previous release. If you would like to edit
68 them, this can be done by updating the changes in the release PR.
691. To cut a release, approve and merge the pull request. Doing so will
70 update the `CHANGES.md`, tag the merged commit with the appropriate version,
71 and draft a GitHub release which will copy the notes from `CHANGES.md`.
72
73### Manual Release (`cloud.google.com/go`)
74
75If for whatever reason the automated release process is not working as expected,
76here is how to manually cut a release of `cloud.google.com/go`.
77
781. Check for failures in the
79 [continuous Kokoro build](http://go/google-cloud-go-continuous). If there are
80 any failures in the most recent build, address them before proceeding with
81 the release.
821. Navigate to `google-cloud-go/` and switch to main.
831. `git pull`
841. Run `git tag -l | grep -v beta | grep -v alpha` to see all existing releases.
85 The current latest tag `$CV` is the largest tag. It should look something
86 like `vX.Y.Z` (note: ignore all `LIB/vX.Y.Z` tags - these are tags for a
87 specific library, not the module root). We'll call the current version `$CV`
88 and the new version `$NV`.
891. On main, run `git log $CV...` to list all the changes since the last
90 release. NOTE: You must manually visually parse out changes to submodules [1]
91 (the `git log` is going to show you things in submodules, which are not going
92 to be part of your release).
931. Edit `CHANGES.md` to include a summary of the changes.
941. In `internal/version/version.go`, update `const Repo` to today's date with
95 the format `YYYYMMDD`.
961. In `internal/version` run `go generate`.
971. Commit the changes, ignoring the generated `.go-r` file. Push to your fork,
98 and create a PR titled `chore: release $NV`.
991. Wait for the PR to be reviewed and merged. Once it's merged, and without
100 merging any other PRs in the meantime:
101 a. Switch to main.
102 b. `git pull`
103 c. Tag the repo with the next version: `git tag $NV`.
104 d. Push the tag to origin:
105 `git push origin $NV`
1061. Update [the releases page](https://github.com/googleapis/google-cloud-go/releases)
107 with the new release, copying the contents of `CHANGES.md`.
108
109### Manual Releases (submodules)
110
111If for whatever reason the automated release process is not working as expected,
112here is how to manually cut a release of a submodule.
113
114(these instructions assume we're releasing `cloud.google.com/go/datastore` - adjust accordingly)
115
1161. Check for failures in the
117 [continuous Kokoro build](http://go/google-cloud-go-continuous). If there are
118 any failures in the most recent build, address them before proceeding with
119 the release. (This applies even if the failures are in a different submodule
120 from the one being released.)
1211. Navigate to `google-cloud-go/` and switch to main.
1221. `git pull`
1231. Run `git tag -l | grep datastore | grep -v beta | grep -v alpha` to see all
124 existing releases. The current latest tag `$CV` is the largest tag. It
125 should look something like `datastore/vX.Y.Z`. We'll call the current version
126 `$CV` and the new version `$NV`.
1271. On main, run `git log $CV.. -- datastore/` to list all the changes to the
128 submodule directory since the last release.
1291. Edit `datastore/CHANGES.md` to include a summary of the changes.
1301. In `internal/version` run `go generate`.
1311. Commit the changes, ignoring the generated `.go-r` file. Push to your fork,
132 and create a PR titled `chore(datastore): release $NV`.
1331. Wait for the PR to be reviewed and merged. Once it's merged, and without
134 merging any other PRs in the meantime:
135 a. Switch to main.
136 b. `git pull`
137 c. Tag the repo with the next version: `git tag $NV`.
138 d. Push the tag to origin:
139 `git push origin $NV`
1401. Update [the releases page](https://github.com/googleapis/google-cloud-go/releases)
141 with the new release, copying the contents of `datastore/CHANGES.md`.
View as plain text