Skip to content

Commit 638c3d0

Browse files
scotthartscotthart
committed
impl: add release scripts and instructions
1 parent 54f6fbc commit 638c3d0

File tree

3 files changed

+645
-0
lines changed

3 files changed

+645
-0
lines changed

‎release/README.md‎

Lines changed: 279 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,279 @@
1+
# Creating a new release of google-cloud-cpp-bigquery
2+
3+
Unless there are no changes, we create releases for `google-cloud-cpp-bigquery` at the
4+
beginning of each month, usually on the first business day. We also create
5+
releases if there is a major announcement or change to the status of one of the
6+
libraries (like reaching the "Alpha" or "Beta" milestone).
7+
8+
The intended audience of this document are developers in the `google-cloud-cpp-bigquery`
9+
project that need to create a new release. We expect the reader to be familiar
10+
the project itself, [git][git-docs], [GitHub][github-guides], and
11+
[semantic versioning](https://semver.org).
12+
13+
## 1. Preparing for a release
14+
15+
To create a new release you need to perform some maintenance tasks, these are
16+
enumerated below.
17+
18+
### a. Verify CI passing
19+
20+
Before beginning the release process, verify all CI builds are passing on the
21+
`main` branch. This is displayed in the GitHub page for the project.
22+
23+
### b. Create a PR to prepare the pre-release
24+
25+
#### Update the root CMakeLists.txt
26+
27+
Set the pre-release version (PROJECT_VERSION_PRE_RELEASE) to the empty string.
28+
29+
```
30+
set(PROJECT_VERSION_PRE_RELEASE "")
31+
```
32+
33+
#### Update the version info
34+
35+
Run any CMake-based build to update
36+
`google/cloud/bigquery_unified/internal/version_info.h`. If you do not feel like
37+
waiting for a build, make the corresponding changes in these files manually.
38+
39+
#### Update CHANGELOG.md
40+
41+
To update the [`CHANGELOG.md`] file, first change the "TBD" placeholder in the
42+
latest release header to the current YYYY-MM.
43+
44+
Then run the script
45+
46+
```bash
47+
git fetch upstream
48+
release/changes.sh
49+
```
50+
51+
to output a summary of the potentially interesting changes since the previous
52+
release. Paste that output below the release header updated above, and manually
53+
tweak as needed.
54+
55+
**NOTE:** If you can, add the script output into the PR description so that
56+
reviewers know what you removed. Or, better yet, leave the description alone,
57+
and use the script output verbatim in the PR (except, perhaps, for obvious
58+
duplications), and then let the normal review/edit/push cycle deal with any
59+
cleanups.
60+
61+
- A change in an existing library warrants its own library section.
62+
- Library sections should be listed in alphabetical order (Update `sections` in
63+
`release/changes.sh`).
64+
- Do not list changes for libraries under development.
65+
- Do not list changes for internal components.
66+
67+
#### Run checkers
68+
69+
```bash
70+
ci/cloudbuild/build.sh -t checkers-pr
71+
```
72+
73+
#### Send a PR with all these changes
74+
75+
```bash
76+
git add .
77+
git checkout -b release-changelog
78+
git commit -am "docs(release): update changelog for the $(date +%Y-%m) release"
79+
git push
80+
```
81+
82+
## 2. Bump the version number in `main`
83+
84+
Working in your fork of `google-cloud-cpp-bigquery`: bump the version numbers to
85+
the *next* version, i.e., one version past the release you just did above. Then
86+
send the PR for review against `main`. You need to:
87+
88+
### a. Make the following changes
89+
90+
- In the top-level `CMakeLists.txt` file:
91+
- a. Increment the version number in the `project()` function.
92+
- b. Set the pre-release version (PROJECT_VERSION_PRE_RELEASE) to "rc".
93+
- In the `CHANGELOG.md` file:
94+
- Add a "vX.Y.Z - TBD" header, corresponding to the new version number.
95+
96+
### b. Run the following script
97+
98+
- Update the ABI baseline to include the new version numbers in the inline
99+
namespace by running `ci/cloudbuild/build.sh -t check-api-pr`. This will leave
100+
the updated ABI files in `ci/abi-dumps`, and also update the
101+
`google/cloud/bigquery_unified/internal/version_info.h`.
102+
103+
This will step will take a while. You can leave this and move onto step 3.
104+
105+
### c. Send the PR for review
106+
107+
**NOTE:** Do NOT send this PR for review before the release is created in step
108+
3\.
109+
110+
```bash
111+
git add .
112+
git checkout -b bump-rc
113+
git commit -am "chore: version bump to $(sed -n 's/.* VERSION //p' CMakeLists.txt)-rc"
114+
git push
115+
```
116+
117+
**NOTE:** The Renovate bot will automatically update the Bazel deps in the
118+
quickstart `WORKSPACE.bazel` files after it sees the new release published.
119+
Watch for this PR to come through, kick off the builds, approve, and merge it.
120+
121+
## 3. Creating the release
122+
123+
**NOTE:** Do NOT create the release branch before the PR created in step 1 is
124+
*merged*.
125+
126+
We want to create the release from a stable point in the default branch
127+
(`main`), and we want this point to include the updated release notes. There may
128+
be exceptions to this guideline, you are encouraged to use your own judgment.
129+
130+
### a. Run the release script
131+
132+
We next need to create the release tag, the release branch, and create the
133+
release in the GitHub UI. We use a script ([`release/release.sh`]) to automate
134+
said steps.
135+
136+
*No PR is needed for this step.*
137+
138+
First run the following command -- which will *NOT* make any changes to the repo
139+
-- and verify that the output and *version numbers* look correct.
140+
141+
```bash
142+
release/release.sh googleapis/google-cloud-cpp-bigquery
143+
```
144+
145+
If the output from the previous command looks OK, rerun the command with the
146+
`-f` flag, which will make the changes and push them to the remote repo.
147+
148+
```bash
149+
release/release.sh -f googleapis/google-cloud-cpp-bigquery
150+
```
151+
152+
**NOTE:** This script can be run from any directory. It operates only on the
153+
specified repo.
154+
155+
### b. Publish the release
156+
157+
Review the new release in the GitHub web UI (the link to the pre-release will be
158+
output from the `release.sh` script that was run in the previous step). If
159+
everything looks OK:
160+
161+
1. Uncheck the pre-release checkbox.
162+
1. Check the latest release checkbox.
163+
1. Click the update release button.
164+
165+
## 4. Check the published reference docs
166+
167+
The `publish-docs-release` build should start automatically when you create the
168+
release branch. This build will upload the docs for the new release to the
169+
following URLs:
170+
171+
- https://cloud.google.com/cpp/docs/reference/
172+
173+
It can take up to a day after the build finishes for the new docs to show up at
174+
the above URL. You can watch the status of the build at
175+
https://console.cloud.google.com/cloud-build/builds;region=us-east4?project=cloud-cpp-testing-resources&query=tags%3D%22publish-docs%22
176+
177+
## 5. Review the protections for the `v[0-9].*` branches
178+
179+
We use the [GitHub Branch Settings][github-branch-settings] to protect the
180+
release branches against accidental mistakes. From time to time changes in the
181+
release branch naming conventions may require you to change these settings.
182+
Please note that we use more strict settings for release branches than for
183+
`main`, in particular:
184+
185+
- We require at least one review, but stale reviews are dismissed.
186+
187+
- The `Require status checks to pass before merging` option is set. This
188+
prevents merges into the release branches that break the build.
189+
190+
- The `Require branches to be up to date before merging` sub-option is set.
191+
This prevents two merges that do not conflict, but nevertheless break if
192+
both are pushed, to actually merge.
193+
- _At a minimum_ the `cla/google`, `asan-pr`, and `clang-tidy-pr` checks
194+
should be marked as "required". You may consider adding additional builds if
195+
it would prevent embarrassing failures, but consider the tradeoff of merges
196+
blocked by flaky builds.
197+
198+
- The `Include administrators` checkbox is turned on, we want to stop ourselves
199+
from making mistakes.
200+
201+
- Turn on the `Restrict who can push to matching branches`. Only Google team
202+
members should be pushing to release branches.
203+
204+
# Creating a patch release of google-cloud-cpp-bigquery on an existing release branch
205+
206+
In your development fork:
207+
208+
- We will use `BRANCH=v2.15.x` and `PATCH=v2.15.1` as an example.
209+
- Set these shell variables to appropriate values.
210+
- Create a new branch
211+
```shell
212+
git branch chore-prepare-for-${PATCH}-release upstream/${BRANCH}
213+
git checkout chore-prepare-for-${PATCH}-release
214+
```
215+
- Bump the version numbers for the patch release
216+
- Update the minor version in the top-level `CMakeLists.txt` file.
217+
```shell
218+
git commit -m"chore: prepare for ${PATCH}"
219+
```
220+
- If this is the first patch release for that branch, you need to update the GCB
221+
triggers.
222+
- Update the Google Cloud Build trigger definitions to compile this branch:
223+
```shell
224+
ci/cloudbuild/convert-to-branch-triggers.sh --branch "${BRANCH}"
225+
```
226+
- Actually create the triggers in GCB:
227+
```shell
228+
for trigger in $(git ls-files -- ci/cloudbuild/triggers/*.yaml ); do
229+
ci/cloudbuild/trigger.sh --import "${trigger}";
230+
done
231+
```
232+
- Remove any old triggers for the same major version, e.g.:
233+
```shell
234+
gcloud builds triggers list \
235+
--project=cloud-cpp-testing-resources \
236+
--filter=name:v2-10-x --format='value(id)' | \
237+
xargs -n 1 gcloud builds triggers delete \
238+
--project=cloud-cpp-testing-resources
239+
```
240+
- Commit these changes:
241+
```shell
242+
git commit -m"Updated GCB triggers" ci
243+
```
244+
- Push the branch and then create a PR:
245+
```shell
246+
git push --set-upstream origin "$(git branch --show-current)"
247+
```
248+
249+
______________________________________________________________________
250+
251+
## Send this PR for review and merge it before continuing
252+
253+
- Create a new branch off the release branch, which now contains the new patch
254+
version and baseline ABI dumps.
255+
```shell
256+
git fetch upstream
257+
git branch my-patch upstream/${BRANCH}
258+
git checkout my-patch
259+
```
260+
- Create or cherry-pick commits with the desired changes.
261+
- Update `CHANGELOG.md` to reflect the changes made.
262+
- After merging the PR(s) with all the above changes, create the tag:
263+
```shell
264+
git fetch upstream ${BRANCH}
265+
git checkout upstream/${BRANCH}
266+
git tag ${PATCH}
267+
git push upstream ${PATCH}
268+
```
269+
- Use the Release UI on GitHub to create a pre-release from the new tag. Uncheck
270+
the "Set as the latest release" box if this is not the latest release.
271+
- After review, publish the release.
272+
- Update our [vcpkg port].
273+
274+
[git-docs]: https://git-scm.com/doc
275+
[github-branch-settings]: https://github.com/googleapis/google-cloud-cpp/settings/branches
276+
[github-guides]: https://guides.github.com/
277+
[vcpkg port]: https://github.com/Microsoft/vcpkg/tree/master/ports/google-cloud-cpp
278+
[`changelog.md`]: /CHANGELOG.md
279+
[`release/release.sh`]: https://github.com/googleapis/google-cloud-cpp/blob/main/release/release.sh

0 commit comments

Comments
 (0)