Skip to content
This repository was archived by the owner on Dec 8, 2021. It is now read-only.

Commit 1dcddd5

Browse files
coryancoryan
authored
doc: update release notes for release (#623)
1 parent 20f3590 commit 1dcddd5

File tree

2 files changed

+156
-2
lines changed

2 files changed

+156
-2
lines changed

‎README.md‎

Lines changed: 15 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,8 @@ level. The library should be usable for experimental code, but we do not
2020
recommend that you use this library for production workloads. Please note that,
2121
as is often the case with C++ libraries, we do **not** follow semantic
2222
versioning in the Cloud C++ client libraries. We make every effort to document
23-
backwards-incompatible API changes in the [release notes](#release-notes) below.
23+
backwards-incompatible API changes in the
24+
[release notes](README.md#release-notes) below.
2425

2526
<!-- Start of automatically generated content by ci/generate-badges.sh -->
2627

@@ -115,7 +116,19 @@ Apache 2.0; see [`LICENSE`](LICENSE) for details.
115116

116117
## Release Notes
117118

118-
### v0.1.x - TBD
119+
### v0.1.x - 2019-09
120+
121+
* This is the initial Alpha release of the library.
122+
* While this version is not recommended for production workloads it is stable
123+
enough to use in experimental code. We welcome feedback about the library
124+
through [GitHub issues][GitHub-new-issue].
125+
* The API is expected to undergo incompatible changes before Beta and GA.
126+
* The library supports all the operations to read and write data into Cloud
127+
Spanner.
128+
* The library supports some administrative operations such as creating,
129+
updating, and dropping databases.
130+
131+
[GitHub-new-issue]: https://github.com/googleapis/google-cloud-cpp-spanner/issues/new
119132

120133
## Versioning
121134

‎doc/cutting-a-release.md‎

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
# Creating a new release of google-cloud-cpp-spanner
2+
3+
Unless there are no changes, we create releases for `google-cloud-cpp-spanner`
4+
every month, or if there is a major announcement or change to the status of the
5+
library.
6+
7+
The intended audience of this document are developers in the
8+
`google-cloud-cpp-spanner` project that need to create a new release. The
9+
audience is expected to be familiar with the project itself, [git][git-docs],
10+
[GitHub][github-guides], and [semantic versioning](https://semver.org).
11+
12+
## Preparing for a release
13+
14+
First you should collect and update the release notes for the project. Prepare
15+
a pull request (PR) with the necessary changes to the README files in each
16+
project.
17+
18+
Assuming you are working on your own fork of the `google-cloud-cpp-spanner`
19+
project, and `upstream` points to the `googleapis/google-cloud-cpp-spanner`
20+
remote, these commands should be useful in identifying important changes:
21+
22+
```bash
23+
# Summarize the output of this into google/cloud/spanner/README.md
24+
git log upstream/master
25+
```
26+
27+
It is not recommended that you create the release branch before this PR is
28+
ready, but in some circumstances it might be needed, for example, if a large
29+
change that could destabilize the release is about to be merged, or if we want
30+
to create the release at an specific point in the revision history.
31+
32+
## Create the release branch
33+
34+
To find the next release number, look at the existing branch names on the
35+
`upstream` repo and select the next available "v.0.N" version number.
36+
37+
```bash
38+
git remote show upstream
39+
```
40+
41+
Throughout this document we will use this variable to represent the release
42+
name:
43+
44+
```bash
45+
# Use the actual release prefix (e.g. v0.5) not just `N`.
46+
export RELEASE="v0.N"
47+
```
48+
49+
50+
If you decide to cut&paste the commands below, make sure that variable has the
51+
actual release value, e.g. `v0.5` or `v0.7`, and not the generic `N`.
52+
53+
Clone the main repository to create the tags and branch:
54+
55+
```bash
56+
git clone [email protected]:googleapis/google-cloud-cpp-spanner.git releases
57+
cd releases
58+
```
59+
60+
Create a tag for the new release.
61+
62+
```bash
63+
git tag "${RELEASE}.0"
64+
git push origin "${RELEASE}.0"
65+
```
66+
67+
Create a new branch based on that tag and push the branch to the upstream repository:
68+
69+
```bash
70+
git checkout -b "${RELEASE}.x" "${RELEASE}.0"
71+
git push --set-upstream origin "${RELEASE}.x"
72+
```
73+
74+
This will start a CI build cycle. The builds *should* pass, as we normally keep
75+
`master` in a releasable state.
76+
77+
**NOTE:** No code review or Pull Request is needed as part of this step.
78+
79+
## Create pre-release for review.
80+
81+
Create a pre-release using
82+
[GitHub](https://github.com/googleapis/google-cloud-cpp-spanner/releases/new).
83+
Use the tag that you just created ("${RELEASE}.0").
84+
Make sure to check the `pre-release` checkbox.
85+
86+
Copy the relevant release notes into the description of the release.
87+
88+
After you create the release, capture the SHA256 checksums of the
89+
tarball and zip files, and edit the notes to include them. These
90+
commands might be handy:
91+
92+
```bash
93+
TAG="${RELEASE}.0" # change this to the actual tag
94+
wget -q -O - "https://github.com/googleapis/google-cloud-cpp-spanner/archive/${TAG}.tar.gz" | sha256sum
95+
wget -q -O - "https://github.com/googleapis/google-cloud-cpp-spanner/archive/${TAG}.zip" | sha256sum
96+
```
97+
98+
You can publish this release once the notes are updated.
99+
100+
### Ask your colleagues to review the release notes.
101+
102+
Edit the notes as needed.
103+
104+
### Publish the release
105+
106+
Uncheck the pre-release checkbox and publish.
107+
108+
<!-- TODO(...) - include instructions to upload docs to googleapis.dev -->
109+
110+
## Bump the version numbers in `master`
111+
112+
Working in your fork of `gooogle-cloud-cpp-spanner`: bump the version numbers
113+
to the *next* version (i.e., one version past the release you just did above),
114+
and send the PR for review against `master`.
115+
116+
## Review the branch protections
117+
118+
We use the [GitHub Branch Settings][github-branch-settings] to protect the
119+
release branches against accidental mistakes. From time to time changes in the
120+
release branch naming conventions may require you to change these settings.
121+
Please note that we use more strict settings for release branches than for
122+
`master`, in particular:
123+
124+
* We require at least one review, but stale reviews are dismissed.
125+
* The `Require status checks to pass before merging` option is set.
126+
This prevents merges into the release branches that break the build.
127+
* The `Require branches to be up to date before merging` sub-option
128+
is set. This prevents two merges that do not conflict, but nevertheless
129+
break if both are pushed, to actually merge.
130+
* The `Kokoro Ubuntu`, `Kokoro Windows`, `cla/google`, and
131+
`continuous-integration/travis-ci` checks are required to pass.
132+
133+
* The `Include administrators` checkbox is turned on, we want to stop ourselves
134+
from making mistakes.
135+
136+
* Turn on the `Restrict who can push to matching branches`. Only Google team
137+
members should be pushing to release branches.
138+
139+
[git-docs]: https://git-scm.com/doc
140+
[github-guides]: https://guides.github.com/
141+
[github-branch-settings]: https://github.com/googleapis/google-cloud-cpp-spanner/settings/branches

0 commit comments

Comments
 (0)