1# Releasing
2
3## Setup environment from scratch
4
51. [Install Go](https://golang.org/dl/).
6    1. Ensure that your `GOBIN` directory (by default `$(go env GOPATH)/bin`)
7    is in your `PATH`.
8    1. Check it's working by running `go version`.
9        * If it doesn't work, check the install location, usually
10        `/usr/local/go`, is on your `PATH`.
11
121. Sign one of the
13[contributor license agreements](#contributor-license-agreements) below.
14
151. Clone the repo:
16    `git clone https://github.com/googleapis/google-cloud-go`
17
181. Change into the checked out source:
19    `cd google-cloud-go`
20
211. Fork the repo and add your fork as a secondary remote (this is necessary in
22   order to create PRs).
23
24## Determine which module to release
25
26The Go client libraries have several modules. Each module does not strictly
27correspond to a single library - they correspond to trees of directories. If a
28file needs to be released, you must release the closest ancestor module.
29
30To see all modules:
31
32```bash
33$ cat `find . -name go.mod` | grep module
34module cloud.google.com/go
35module cloud.google.com/go/bigtable
36module cloud.google.com/go/firestore
37module cloud.google.com/go/bigquery
38module cloud.google.com/go/storage
39module cloud.google.com/go/datastore
40module cloud.google.com/go/pubsub
41module cloud.google.com/go/spanner
42module cloud.google.com/go/logging
43```
44
45The `cloud.google.com/go` is the repository root module. Each other module is
46a submodule.
47
48So, if you need to release a change in `bigtable/bttest/inmem.go`, the closest
49ancestor module is `cloud.google.com/go/bigtable` - so you should release a new
50version of the `cloud.google.com/go/bigtable` submodule.
51
52If you need to release a change in `asset/apiv1/asset_client.go`, the closest
53ancestor module is `cloud.google.com/go` - so you should release a new version
54of the `cloud.google.com/go` repository root module. Note: releasing
55`cloud.google.com/go` has no impact on any of the submodules, and vice-versa.
56They are released entirely independently.
57
58## Test failures
59
60If there are any test failures in the Kokoro build, releases are blocked until
61the failures have been resolved.
62
63## How to release `cloud.google.com/go`
64
65Check for failures in the [continuous Kokoro build](http://go/google-cloud-go-continuous).
66If there are any failures in the most recent build, address them before
67proceeding with the release.
68
69### Automated Release
70
71If there are changes that have not yet been released a
72[pull request](https://github.com/googleapis/google-cloud-go/pull/2971) should
73be automatically opened by [release-please](https://github.com/googleapis/release-please)
74with a title like "chore: release 0.XX.0", where XX is the next version to be
75released. To cut a release, approve and merge this pull request. Doing so will
76update the `CHANGES.md`, tag the merged commit with the appropriate version,
77and draft a GitHub release.
78
79### Manual Release
80
81If for whatever reason the automated release process is not working as expected,
82here is how to manually cut a release.
83
841. Navigate to `google-cloud-go/` and switch to master.
851. `git pull`
861. Run `git tag -l | grep -v beta | grep -v alpha` to see all existing releases.
87   The current latest tag `$CV` is the largest tag. It should look something
88   like `vX.Y.Z` (note: ignore all `LIB/vX.Y.Z` tags - these are tags for a
89   specific library, not the module root). We'll call the current version `$CV`
90   and the new version `$NV`.
911. On master, run `git log $CV...` to list all the changes since the last
92   release. NOTE: You must manually visually parse out changes to submodules [1]
93   (the `git log` is going to show you things in submodules, which are not going
94   to be part of your release).
951. Edit `CHANGES.md` to include a summary of the changes.
961. In `internal/version/version.go`, update `const Repo` to today's date with
97   the format `YYYYMMDD`.
981. In `internal/version` run `go generate`.
991. Commit the changes, ignoring the generated `.go-r` file. Push to your fork,
100   and create a PR titled `chore: release $NV`.
1011. Wait for the PR to be reviewed and merged. Once it's merged, and without
102   merging any other PRs in the meantime:
103   a. Switch to master.
104   b. `git pull`
105   c. Tag the repo with the next version: `git tag $NV`.
106   d. Push the tag to origin:
107      `git push origin $NV`
1081. Update [the releases page](https://github.com/googleapis/google-cloud-go/releases)
109   with the new release, copying the contents of `CHANGES.md`.
110
111## How to release a submodule
112
113We have several submodules, including `cloud.google.com/go/logging`,
114`cloud.google.com/go/datastore`, and so on.
115
116To release a submodule:
117
118(these instructions assume we're releasing `cloud.google.com/go/datastore` - adjust accordingly)
119
1201. Check for failures in the
121   [continuous Kokoro build](http://go/google-cloud-go-continuous). If there are
122   any failures in the most recent build, address them before proceeding with
123   the release. (This applies even if the failures are in a different submodule
124   from the one being released.)
1251. Navigate to `google-cloud-go/` and switch to master.
1261. `git pull`
1271. Run `git tag -l | grep datastore | grep -v beta | grep -v alpha` to see all
128   existing releases. The current latest tag `$CV` is the largest tag. It
129   should look something like `datastore/vX.Y.Z`. We'll call the current version
130   `$CV` and the new version `$NV`.
1311. On master, run `git log $CV.. -- datastore/` to list all the changes to the
132   submodule directory since the last release.
1331. Edit `datastore/CHANGES.md` to include a summary of the changes.
1341. In `internal/version` run `go generate`.
1351. Commit the changes, ignoring the generated `.go-r` file. Push to your fork,
136   and create a PR titled `chore(datastore): release $NV`.
1371. Wait for the PR to be reviewed and merged. Once it's merged, and without
138   merging any other PRs in the meantime:
139   a. Switch to master.
140   b. `git pull`
141   c. Tag the repo with the next version: `git tag $NV`.
142   d. Push the tag to origin:
143      `git push origin $NV`
1441. Update [the releases page](https://github.com/googleapis/google-cloud-go/releases)
145   with the new release, copying the contents of `datastore/CHANGES.md`.
146
147## Appendix
148
1491: This should get better as submodule tooling matures.
150