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