Skip to content

Commit 243c3c2

Browse files
blowmageblowmage
authored
Remove JSONDOC (googleapis#2355)
* Remove jsondoc rake tasks. * Remove docs directory and files. * Move guides to gem-root directories, and uppercase file names. * Update RELEASING guide.
1 parent 26ae57d commit 243c3c2

137 files changed

Lines changed: 224 additions & 5527 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎RELEASING.md‎

Lines changed: 110 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -1,119 +1,183 @@
11
# Releasing Google Cloud Ruby Client
22

3-
These instructions apply to every gem within the Google Cloud Ruby Client project.
3+
These instructions apply to every gem within the Google Cloud Ruby Client
4+
project.
45

56
## Releasing individual gems and meta-packages
67

7-
**Each gem must be released separately.** In order for the docs for the `google-cloud` package to build correctly, the only entry in `docs/manifest.json` that can be updated in the version commit preceding the release tag is the entry for the gem in the tag. The docs build will fail if you attempt to release multiple gems in parallel, since the first tag build will not yet find the listed docs for the other gems in the `gh-pages` branch.
8+
The Google Cloud Ruby Client project uses [semantic
9+
versioning](http://semver.org). Replace the `<prev_version>` and `<version>`
10+
placeholders shown in the examples below with the appropriate numbers, e.g.
11+
`0.1.0` and `0.2.0`. Replace the `<gem>` placeholder with the appropriate full
12+
name of the package, e.g. `google-cloud-datastore`.
813

9-
The Google Cloud Ruby Client project uses [semantic versioning](http://semver.org). Replace the `<prev_version>` and `<version>` placeholders shown in the examples below with the appropriate numbers, e.g. `0.1.0` and `0.2.0`. Replace the `<gem>` placeholder with the appropriate full name of the package, e.g. `google-cloud-datastore`.
14+
After all [pull
15+
requests](https://github.com/GoogleCloudPlatform/google-cloud-ruby/pulls) for a
16+
release have been merged and all Kokoro and [Circle CI
17+
builds](https://circleci.com/gh/GoogleCloudPlatform/google-cloud-ruby) are
18+
green, you may create a release as follows:
1019

11-
After all [pull requests](https://github.com/GoogleCloudPlatform/google-cloud-ruby/pulls) for a release have been merged and all [Circle CI builds](https://circleci.com/gh/GoogleCloudPlatform/google-cloud-ruby) are green, you may create a release as follows:
12-
13-
1. If you haven't already, switch to the master branch, ensure that you have no changes, and pull from origin.
20+
1. If you haven't already, switch to the master branch, ensure that you have no
21+
changes, and pull from origin.
1422

1523
```sh
1624
$ git checkout master
1725
$ git status
1826
$ git pull <remote> master --rebase
1927
```
2028

21-
1. Build the gem locally. (Depending on your environment, you may need to `bundle exec` to rake commands; this will be shown.)
29+
2. Build the gem locally. (Depending on your environment, you may need to
30+
`bundle exec` to rake commands; this will be shown.)
2231

2332
```sh
2433
$ cd <gem>
2534
$ bundle exec rake build
2635
```
2736

28-
1. Install the gem locally. (The `rake install` task shown below may not always work as expected. Fall back to running `gem install` in an empty gemset if needed.)
37+
3. Install the gem locally. (The `rake install` task shown below may not always
38+
work as expected. Fall back to running `gem install` in an empty gemset if
39+
needed.)
2940

3041
```sh
3142
$ bundle exec rake install
3243
```
3344

34-
1. Using IRB (not `rake console`!), manually test the gem that you installed in the previous step.
45+
4. Using IRB (not `rake console`!), manually test the gem that you installed in
46+
the previous step.
3547

36-
1. Return to the root directory of the project, and review the changes since the last release.
48+
5. Return to the root directory of the project, and review the changes since the
49+
last release.
3750

3851
```sh
3952
$ cd ..
4053
$ bundle exec rake changes[<gem>]
4154
```
4255

43-
1. Review the commits in the changes output, making notes of significant changes. (For examples of what a significant change is, browse the changes in the gem's `CHANGELOG.md`.
44-
45-
1. Edit the gem's `CHANGELOG.md`. Using your notes from the previous step, write bullet-point lists of the major and minor changes. You can also add examples, fixes, thank yous, and anything else helpful or relevant. See google-cloud-node [v0.18.0](https://github.com/GoogleCloudPlatform/google-cloud-node/releases/tag/v0.18.0) for an example with all the bells and whistles.
46-
47-
1. Edit the gem's `version.rb` file, if present, or the `version` setting in its `.gemspec` file, changing the value to your new version number.
48-
49-
1. Edit (or add if new) the gem's entry in `docs/manifest.json`, adding your new version number to the head of the list, and moving `"master"` to be just below it.
50-
51-
1. If your package is new, ensure that it has been added to the [top-level `Gemfile`](https://github.com/GoogleCloudPlatform/google-cloud-ruby/blob/google-cloud/v0.52.0/Gemfile).
52-
Follow the steps in [Adding a new gem to meta-packages](#adding-a-new-gem-to-meta-packages), below.
53-
54-
1. If the [semver](http://semver.org/) version change for your package requires an increase in the requirement for your package in `google-cloud/google-cloud.gemspec` and/or `stackdriver/stackdriver.gemspec`, replace the old version requirement with your new requirement. Note that because of the use of the [pessimistic operator (`~>`)](https://robots.thoughtbot.com/rubys-pessimistic-operator), only certain version changes will require updating the requirement. Note also that the dependency requirements in the `google-cloud` and `stackdriver` gems must remain compatible so the two can co-exist in the same bundle.
55-
56-
1. If your package is new, ensure that a nav link and a main entry including code example have been added to the [top-level README](https://github.com/GoogleCloudPlatform/google-cloud-ruby/blob/google-cloud/v0.52.0/README.md).
57-
58-
1. In the root directory of the project, test that all the version dependencies are correct.
56+
6. Review the commits in the changes output, making notes of significant
57+
changes. (For examples of what a significant change is, browse the changes in
58+
the gem's `CHANGELOG.md`.)
59+
60+
7. Edit the gem's `CHANGELOG.md`. Using your notes from the previous step, write
61+
bullet-point lists of the major and minor changes. You can also add examples,
62+
fixes, thank yous, and anything else helpful or relevant. See
63+
google-cloud-node
64+
[v0.18.0](https://github.com/GoogleCloudPlatform/google-cloud-node/releases/tag/v0.18.0)
65+
for an example with all the bells and whistles.
66+
67+
8. Edit the gem's `version.rb` file, if present, or the `version` setting in its
68+
`.gemspec` file, changing the value to your new version number.
69+
70+
9. If your package is new, ensure that it has been added to the [top-level
71+
`Gemfile`](https://github.com/GoogleCloudPlatform/google-cloud-ruby/blob/google-cloud/v0.52.0/Gemfile).
72+
Follow the steps in [Adding a new gem to
73+
meta-packages](#adding-a-new-gem-to-meta-packages), below.
74+
75+
10. If the [semver](http://semver.org/) version change for your package requires
76+
an increase in the requirement for your package in
77+
`google-cloud/google-cloud.gemspec` and/or
78+
`stackdriver/stackdriver.gemspec`, replace the old version requirement with
79+
your new requirement. Note that because of the use of the [pessimistic
80+
operator (`~>`)](https://robots.thoughtbot.com/rubys-pessimistic-operator),
81+
only certain version changes will require updating the requirement. Note
82+
also that the dependency requirements in the `google-cloud` and
83+
`stackdriver` gems must remain compatible so the two can co-exist in the
84+
same bundle.
85+
86+
11. If your package is new, ensure that a nav link and a main entry including
87+
code example have been added to the [top-level
88+
README](https://github.com/GoogleCloudPlatform/google-cloud-ruby/blob/google-cloud/v0.52.0/README.md).
89+
90+
12. In the root directory of the project, test that all the version dependencies
91+
are correct.
5992
6093
```sh
6194
$ bundle update
6295
$ bundle exec rake ci[yes]
6396
```
6497
65-
1. Commit your changes. Copy and paste the significant points from your `CHANGELOG.md` edit as the description in your commit message.
98+
13. Commit your changes. Copy and paste the significant points from your
99+
`CHANGELOG.md` edit as the description in your commit message.
66100
67101
```sh
68102
$ git commit -am "Release <gem> <version> ..."
69103
```
70104
71-
1. Tag the version.
105+
14. Tag the version.
72106
73107
```sh
74108
$ git tag <gem>/v<version>
75109
```
76110
77-
1. Push the tag. This will trigger a build job on [Circle CI](https://circleci.com/gh/GoogleCloudPlatform/google-cloud-ruby).
111+
15. Push the tag. This will trigger a build job on [Circle
112+
CI](https://circleci.com/gh/GoogleCloudPlatform/google-cloud-ruby).
78113
79114
```sh
80115
$ git push <remote> <gem>/v<version>
81116
```
82117
83-
1. Wait until the [Circle CI build](https://circleci.com/gh/GoogleCloudPlatform/google-cloud-ruby) has passed for the tag.
118+
16. Wait until the [Circle CI
119+
build](https://circleci.com/gh/GoogleCloudPlatform/google-cloud-ruby) has
120+
passed for the tag.
84121
85-
1. Confirm that the new version is displayed on the [google-cloud-ruby gh-pages doc site](http://googlecloudplatform.github.io/google-cloud-ruby/), both in the packages pulldown and the version switcher.
122+
17. Confirm that the new version is displayed on the [google-cloud-ruby gh-pages
123+
doc
124+
site](https://http://googlecloudplatform.github.io/google-cloud-ruby/docs/).
86125
87-
If the gh-pages doc site has not been updated, inspect the build logs to confirm that the release task completed successfully, and that the docs build succeeded. This can still fail even on a green build because it is an "after" action in the build.
126+
If the gh-pages doc site has not been updated, inspect the build logs to
127+
confirm that the release task completed successfully, and that the docs
128+
build succeeded. This can still fail even on a green build because it is an
129+
"after" action in the build.
88130
89-
1. Confirm that the gem for the new version is available on [RubyGems.org](https://rubygems.org/gems/google-cloud).
131+
18. Confirm that the gem for the new version is available on
132+
[RubyGems.org](https://rubygems.org/gems/google-cloud).
90133
91-
1. On the [google-cloud-ruby releases page](https://github.com/GoogleCloudPlatform/google-cloud-ruby/releases), click [Draft a new release](https://github.com/GoogleCloudPlatform/google-cloud-ruby/releases/new). Complete the form. Include the bullet-point lists of the major and minor changes from the gem's `CHANGELOG.md`. You can also add examples, fixes, thank yous, and anything else helpful or relevant. See google-cloud-node [v0.18.0](https://github.com/GoogleCloudPlatform/google-cloud-node/releases/tag/v0.18.0) for an example with all the bells and whistles.
134+
19. On the [google-cloud-ruby releases
135+
page](https://github.com/GoogleCloudPlatform/google-cloud-ruby/releases),
136+
click [Draft a new
137+
release](https://github.com/GoogleCloudPlatform/google-cloud-ruby/releases/new).
138+
Complete the form. Include the bullet-point lists of the major and minor
139+
changes from the gem's `CHANGELOG.md`. You can also add examples, fixes,
140+
thank yous, and anything else helpful or relevant. See google-cloud-node
141+
[v0.18.0](https://github.com/GoogleCloudPlatform/google-cloud-node/releases/tag/v0.18.0)
142+
for an example with all the bells and whistles.
92143

93-
1. Click `Publish release`.
144+
20. Click `Publish release`.
94145

95-
1. Repeat steps 1 through 21 if you are releasing multiple gems.
146+
21. Repeat steps 1 through 20 if you are releasing multiple gems.
96147

97-
1. If you updated `google-cloud/google-cloud.gemspec` for a version change to any gem, repeat steps 1 through 21 for the `google-cloud` gem.
148+
22. If you updated `google-cloud/google-cloud.gemspec` for a version change to
149+
any gem, repeat steps 1 through 21 for the `google-cloud` gem.
98150

99-
1. If you updated `stackdriver/stackdriver.gemspec` for a version change to any gem, repeat steps 1 through 21 for the `stackdriver` gem.
151+
23. If you updated `stackdriver/stackdriver.gemspec` for a version change to any
152+
gem, repeat steps 1 through 21 for the `stackdriver` gem.
100153

101-
1. Wait until the last tag build job has successfully completed on Circle CI. Then push your commits to the master branch. This will trigger another [Circle CI](https://circleci.com/gh/GoogleCloudPlatform/google-cloud-ruby) build on master branch.
154+
24. Wait until the last tag build job has successfully completed on Circle CI.
155+
Then push your commits to the master branch. This will trigger another
156+
[Circle CI](https://circleci.com/gh/GoogleCloudPlatform/google-cloud-ruby)
157+
build on master branch.
102158

103159
```sh
104160
$ git push <remote> master
105161
```
106162

107-
1. After the Circle CI master branch build has successfully completed, confirm that [Travis CI (Mac OS X)](https://travis-ci.org/GoogleCloudPlatform/google-cloud-ruby) and [Appveyor CI (Windows)](https://ci.appveyor.com/project/GoogleCloudPlatform/google-cloud-ruby) master branch builds are also green.
163+
25. After the Circle CI master branch build has successfully completed, confirm
164+
that Kokoro and [Travis CI (Mac OS
165+
X)](https://travis-ci.org/GoogleCloudPlatform/google-cloud-ruby) and
166+
[Appveyor CI
167+
(Windows)](https://ci.appveyor.com/project/GoogleCloudPlatform/google-cloud-ruby)
168+
master branch builds are also green.
108169

109170
High fives all around!
110171

111172
## Adding a new gem to meta-packages
112173

113-
There are extra steps required to add a new package to the `google-cloud` and/or `stackdriver` meta-package gems. These instructions are for the `google-cloud` gem. (The `stackdriver` gem does not require the documentation steps.)
174+
There are extra steps required to add a new package to the `google-cloud` and/or
175+
`stackdriver` meta-package gems. These instructions are for the `google-cloud`
176+
gem.
114177

115-
1. Add the gem to [`google-cloud/Gemfile`](https://github.com/GoogleCloudPlatform/google-cloud-ruby/blob/google-cloud/v0.52.0/google-cloud/Gemfile).
116-
1. Add the gem to [`google-cloud/google-cloud.gemspec`](https://github.com/GoogleCloudPlatform/google-cloud-ruby/blob/google-cloud/v0.52.0/google-cloud/google-cloud.gemspec).
117-
1. Add the gem to [`gcloud/Gemfile`](https://github.com/GoogleCloudPlatform/google-cloud-ruby/blob/google-cloud/v0.52.0/gcloud/Gemfile).
118-
1. Copy the JSON fragment from the gem's `docs/toc.json` to correct alphabetical location in [`google-cloud/docs/toc.json`](https://github.com/GoogleCloudPlatform/google-cloud-ruby/blob/google-cloud/v0.52.0/google-cloud/docs/toc.json).
119-
1. Add the gem to the [`google-cloud` whitelist in the top-level `Rakefile`](https://github.com/GoogleCloudPlatform/google-cloud-ruby/blob/google-cloud/v0.52.0/Rakefile#L290-L317).
178+
1. Add the gem to
179+
[`google-cloud/Gemfile`](https://github.com/GoogleCloudPlatform/google-cloud-ruby/blob/google-cloud/v0.52.0/google-cloud/Gemfile).
180+
2. Add the gem to
181+
[`google-cloud/google-cloud.gemspec`](https://github.com/GoogleCloudPlatform/google-cloud-ruby/blob/google-cloud/v0.52.0/google-cloud/google-cloud.gemspec).
182+
3. Add the gem to
183+
[`gcloud/Gemfile`](https://github.com/GoogleCloudPlatform/google-cloud-ruby/blob/google-cloud/v0.52.0/gcloud/Gemfile).

0 commit comments

Comments
 (0)