Skip to content

Latest commit

 

History

History
175 lines (118 loc) · 12.2 KB

RELEASING.md

File metadata and controls

175 lines (118 loc) · 12.2 KB
Raw

Releasing Google Cloud Ruby Client

These instructions apply to every gem within the Google Cloud Ruby Client project.

Releasing individual gems and meta-packages

After all relevant pull requests for a release have been merged and all Kokoro builds are green, you may create a release as follows:

  1. In root directory of the project, switch to the master branch, ensure that you have no changes, and pull from the project repo.

    $ git checkout master
$ git status
$ git pull <remote> master

  2. Review the report of changes for all gems.

    $ bundle exec rake changes

  3. Choose a gem to release based on the changes report from the previous step. If there are changes to google-cloud-env, google-cloud-core, and/or stackdriver-core, be sure to release them first, in the order listed. Release google-cloud and stackdriver last, in case of dependency changes. (See steps 13 and 14, below.)

  4. In the root directory of the project, from the master branch, review the changes for the gem since its last release.

    $ git pull
$ bundle exec rake changes[<gem>]

  5. Review the commits in the output from the previous step, making note of significant changes. (For examples of what a significant change is, browse the changes in the gem's CHANGELOG.md.)

  6. If your gem is new, follow the steps in Adding a new gem to the top-level package and the meta-packages, below.

  7. If the semver version change for your gem requires an increase in the requirement for your gem 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 (~>), 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.

  8. If your gem is new, ensure that a nav link and a main entry including code example have been added to the top-level README.

  9. Python 3.6 or 3.7 is required. If you do not have Python 3.6 or 3.7 installed we recommend this guide.

  10. Update/Install releasetool with the following:

    $ python3 -m pip install --user --upgrade gcp-releasetool

  11. While on the master branch, cd into the directory of the gem you would like to release, and run:

    $ python3 -m releasetool start

    1. If it's your first time running this, releasetool will likely ask you for a GitHub API token with write:repo_hook and public_repo permissions from https://github.com/settings/tokens.

    2. Next, releasetool will present you with an automatically generated changelog. Use the information from steps 4 and 5, as well as the provided PR numbers to edit and complete the changelog. Remove the "(#111)" style PR references before continuing.

    3. Releasetool will then ask you if your change is considered major, minor, or patch. This project uses semantic versioning.

    4. Releasetool will then create and switch to a branch called release-#{gem-name}-v#{version}, make all the necessary changes to the changelog and gem version, and open a pull request.

  12. Review the PR created by releasetool in the previous step, apply the appropriate label (i.e. api: #{gem_name}), and request a review from googleapis/yoshi-ruby.

  13. Repeat steps 3 through 12 if you are releasing multiple gems.

  14. If you updated google-cloud/google-cloud.gemspec for a version change to any gem, repeat steps 4 through 12 for the google-cloud gem.

  15. If you updated stackdriver/stackdriver.gemspec for a version change to any gem, repeat steps 4 through 12 for the stackdriver gem.

  16. After your pull request has passed all checks and been approved by reviewers, Squash and merge it. Do not delete the branch. Kokoro will create the GitHub release summary and build and push the gem to rubygems. If yoshi-automation reports a failure creating the GitHub release summary, file a bug on releasetool's issue tracker, and write the release manually. If yoshi-automation reports that the release build has failed, follow these steps, selecting the Kokoro build titled "Kokoro - Release".

  17. If everything has gone successfully, yoshi-automation will post twice on the merged PR. Once to provide the status and link for the GitHub release summary, and again to provide the status of the task to publish to rubygems. At this point, please delete the branch created by releasetool in step 11(iv).

  18. Verify the GitHub release summary, making sure that it fits the format of other releases, mirrors the changelog, is tagged to the appropriate commit hash, and is for the correct version.

  19. Verify that the new version is displayed on the google-cloud-ruby doc site at googleapis.dev/ruby/#{gem_name}/latest. The docs are published from the staging bucket every 15 minutes, so it may a few minutes to update.

    If it's been 30 minutes and the docs have not updated, inspect the Kokoro build logs to confirm that the rake release task succeeded.

  20. Verify that the correct version of the gem was published on rubygems.

  21. Verify that the Kokoro Jobs have succeeded. If so, you may now delete the branch belonging to the pull request.

High fives all around!

Adding a new gem to the top-level package and the meta-packages

There are extra steps required to add a new gem to the top-level package and the google-cloud and/or stackdriver meta-package gems. These instructions are for the google-cloud gem.

  1. Add the gem to Gemfile.
  2. Add the gem to google-cloud/Gemfile.
  3. Add the gem to google-cloud/google-cloud.gemspec.
  4. Add the gem to gcloud/Gemfile.

Checking the status of Kokoro builds

  1. On the commits page, find the commit you expect to have launched a Kokoro build.

  2. To the right of your commit, there should be either a red x, or a green checkmark. If it's the green checkmark, your build was a success, and no further inspection is necessary. If it's the red x, click it to find out why the build failed.

  3. A modal will appear with the list of Kokoro builds. The build titled "Kokoro CI" can be ignored. To learn more about why a build failed or what it was testing for click "details" next to the build.

  4. The "details" link will take you to a page on https://source.cloud.google.com/. On the "TARGETS" tab, there will be a link to the logs. It will look like cloud-devrel/client-libraries/google-cloud-ruby/#{job_type}-#{operating_system}. Click the link.

  5. The next page will have a list of all the tasks carried out under the selected operating system. The top half will be a list of tasks and the links to their respective logs, the bottom half will be a list of tasks and their status (SUCCEEDED/FAILED). To learn more about why a task failed, clink the corresponding link on the top half of the screen.

  6. You will be greeted with a screen similar to the one in step 4. The link to your task should look like cloud-devrel/client-libraries/google-cloud-ruby/#{job_type}/#{operating_system}/#{task_name}. Click it.

  7. The "TARGET LOG" tab should be pre-selected, and will contain the complete logs. Examine the logs to determine what went wrong. Before taking the steps below, check to see if the issue appears on the list of known issues. If you see the error there, and you are confident that your release is unrelated, no further steps are necessary.

  8. If you feel the error was transient:

    1. If the error occurred on "Kokoro - Release", selected in step 2, go to the PR containing your release. Unselect the labels "autorelease: published" and "autorelease: failed". This will cause Kokoro to attempt to rebuild and publish the gem you are releasing.

    2. If the error occurred on "Kokoro - Linux", "Kokoro - OSx", or "Kokoro - Windows" and you have access to fusion, find the failing build, click on it, then click "rebuild". If you do not have access to fusion, file an issue containing a link to the build logs, a brief summary, and "@googleapis/yoshi-ruby".

  9. If you feel the error was deterministic:

    1. If you are confident that the error is unrelated to your release, please open an issue with a description of the problem and a link to the build logs.

    2. If the error is related to your release and you have access to the googleapis rubygems account, follow these instructions to yank the gem. Open an issue detailing what went wrong and begin working on a fix.

    3. If the error is related to your release and you do not have access to the googleapis rubygems account, please open an issue containing a link to the build logs, a brief summary, and "@googleapis/yoshi-ruby".

Writing a GitHub release summary manually

  1. Draft a new GitHub release summary.

  2. Add a tag. The tag should be of the format #{gem_name}/v#{version_number}.

  3. To the right of the tag and "@" symbol, there will be a dropdown with "Target: master. Click the dropdown, select the "Recent Commits" tab, and find and select the commit that was your merged PR.

  4. Add a title in the format Release #{gem_name} #{version_number}.

  5. Copy the content of the most recent update in the gem's CHANGELOG.md into the textarea with placeholder text "Describe this release".

  6. Click "Publish release"