README.md
1# Creating a new release of google-cloud-cpp
2
3Unless there are no changes, we create releases for `google-cloud-cpp` every
44 weeks, or if there is a major announcement or change to the status of one
5of the libraries (like reaching the "Alpha" or "Beta" milestone).
6
7The intended audience of this document are developers in the `google-cloud-cpp`
8project that need to create a new release. The audience is expected to be
9familiar with the project itself, [git][git-docs], [GitHub][github-guides],
10[semantic versioning](https://semver.org).
11
12## Preparing for a release
13
14Assuming you are working on your own fork of the `google-cloud-cpp` project,
15and `upstream` points to the `googleapis/google-cloud-cpp` remote, these
16commands should be useful in identifying important changes for inclusion in the
17release notes.
18
19### Update CHANGELOG.md
20
21Update `CHANGELOG.md` based on the release notes for Bigtable, Storage,
22Spanner, and the common libraries:
23
24```bash
25# Summarize the output of this into CHANGELOG.md under the "Bigtable" header
26git log --no-merges --format="format:* %s" \
27 $(git describe --tags --abbrev=0 upstream/master)..HEAD \
28 upstream/master -- google/cloud/bigtable
29```
30
31```bash
32# Summarize the output of this into CHANGELOG.md under the "Storage" header
33git log --no-merges --format="format:* %s" \
34 $(git describe --tags --abbrev=0 upstream/master)..HEAD \
35 upstream/master -- google/cloud/storage
36```
37
38```bash
39# Summarize the output of this into CHANGELOG.md under the "Spanner" header
40git log --no-merges --format="format:* %s" \
41 $(git describe --tags --abbrev=0 upstream/master)..HEAD \
42 upstream/master -- google/cloud/spanner
43```
44
45```bash
46# Summarize the output of this into CHANGELOG.md under the "Common libraries" header
47git log --no-merges --format="format:* %s" \
48 $(git describe --tags --abbrev=0 upstream/master)..HEAD \
49 upstream/master -- google/cloud \
50 ':(exclude)google/cloud/firestore/' \
51 ':(exclude)google/cloud/bigquery/' \
52 ':(exclude)google/cloud/bigtable/' \
53 ':(exclude)google/cloud/pubsub/' \
54 ':(exclude)google/cloud/spanner/' \
55 ':(exclude)google/cloud/storage/'
56```
57
58Any **chore**/**ci**/**test**-tagged PRs in the above lists should probably be
59discarded as they are uninteresting to our users.
60
61### Send a PR with all these changes
62
63It is not recommended that you create the release branch before this PR is
64*merged*, but in some circumstances it might be needed, for example, if a large
65change that could destabilize the release is about to be merged, or if we want
66to create the release at an specific point in the revision history.
67
68## Creating the release
69
70We next need to create the release tag, the release branch, and create the
71release in the GitHub UI. These steps are handled automatically for us by the
72[`./release/release.sh`
73script](https://github.com/googleapis/google-cloud-cpp/blob/master/release/release.sh).
74
75*No PR is needed for this step.*
76
77First run the following command -- which will *NOT* make any changes to any
78repos -- and verify that the output and *version numbers* look correct.
79
80```bash
81$ ./release/release.sh googleapis/google-cloud-cpp
82```
83
84If the output from the previous command looks OK, rerun the command with the
85`-f` flag, which will make the changes and push them to the remote repo.
86
87```bash
88$ ./release/release.sh -f googleapis/google-cloud-cpp
89```
90
91**NOTE:** This script can be run from any directory. It operates only on the
92specified repo.
93
94### Publish the release
95
96Review the new release in the GitHub web UI (the link to the pre-release will
97be output from the `release.sh` script that was run in the previous step). If
98everything looks OK, uncheck the pre-release checkbox and publish.
99
100## Generate and upload the documentation to googleapis.dev
101
102Manually run a Kokoro job
103`cloud-devrel/client-libraries/cpp/google-cloud-cpp/publish-refdocs` in the
104Cloud C++ internal testing dashboard and specify the branch name (e.g.
105`v0.11.x`) in the `Committish` field. This job will generate and upload the
106doxygen documentation to the staging bucket for googleapis.dev hosting. The
107uploaded documentation will generally be live in an hour at the following URLs:
108* https://googleapis.dev/cpp/google-cloud-bigtable/latest/
109* https://googleapis.dev/cpp/google-cloud-storage/latest/
110* https://googleapis.dev/cpp/google-cloud-spanner/latest/
111* https://googleapis.dev/cpp/google-cloud-common/latest/
112
113## Bump the version numbers in `master`
114
115Working in your fork of `google-cloud-cpp`: bump the version numbers to the
116*next* version (i.e., one version past the release you just did above), and
117send the PR for review against `master` You need to:
118
119- Update the version numbers in the top-level `CMakeLists.txt` file.
120- Run the cmake configuration step, this will update the different
121 `version_info.h` files.
122- Update the version number and SHA256 checksums in the
123 `google/cloud/*/quickstart/WORKSPACE` files to point to the *just-released*
124 version.
125
126## Review the protections for the `v[0-9].*` branches
127
128We use the [GitHub Branch Settings][github-branch-settings] to protect the
129release branches against accidental mistakes. From time to time changes in the
130release branch naming conventions may require you to change these settings.
131Please note that we use more strict settings for release branches than for
132`master`, in particular:
133
134* We require at least one review, but stale reviews are dismissed.
135* The `Require status checks to pass before merging` option is set.
136 This prevents merges into the release branches that break the build.
137 * The `Require branches to be up to date before merging` sub-option
138 is set. This prevents two merges that do not conflict, but nevertheless
139 break if both are pushed, to actually merge.
140 * The `Kokoro Ubuntu`, `Kokoro Windows`, `cla/google`, and
141 `continuous-integration/travis-ci` checks are required to pass.
142
143* The `Include administrators` checkbox is turned on, we want to stop ourselves
144 from making mistakes.
145
146* Turn on the `Restrict who can push to matching branches`. Only Google team
147 members should be pushing to release branches.
148
149[git-docs]: https://git-scm.com/doc
150[github-guides]: https://guides.github.com/
151[github-branch-settings]: https://github.com/googleapis/google-cloud-cpp/settings/branches
152
153## Push the release to Microsoft vcpkg
154
155Nudge coryan@ to send a PR to
156[vcpkg](https://github.com/Microsoft/vcpkg/tree/master/ports/google-cloud-cpp).
157The PRs are not difficult, but contributing to this repository requires SVP
158approval.
159