Content Comparison

...

• Double check the PR is eligible for backport as per this linked page.

• Verify that the backport PR does not add a cluster version nor a version gate.
  (i.e. it does not make changes to pkg/clusterversion/cockroach_versions.go nor does it contain checks that compare the current version to one of the newer versions.)
  Ask on #engineering if you need details about why backports must never add cluster versions or version gates.

• Check the release notes in the commit messages, to ensure they are applicable to the branch (if a release note refers to another change / PR that is not being backported, or that may be backported later, suggest a rephrasing.)

Blathers

...

Blathers is a bot deployed to cockroachdb/cockroach and is used to facilitate the backport process. Before using Blathers to create backports one must authenticate with Blathers to allow it to access your cockroachdb/cockroach fork.

1. Clone https://github.com/cockroachlabs/blathers-bot locally on your laptop.

2. Run `go run ./serv/main.go --auth` to initiate the authentication flow and follow the instructions. They will ask you to go to https://github.com/login/device and enter the device code printed out on the command line. Enter the code and verify the script returns with `Successfully saved authentication token. If it fails or hangs, retry, if it still does not work ask #dev-inf for help.

3. Leave the following comment`blathers auth-check` to verify authentication worked. Blathers will respond as you in another comment to say `You shall pass`. If it responds as itself with `You shall not pass`try step 2 above again or ask #dev-inf for help.

4. Navigate to https://github.com/apps/blathers-crl and add your fork to the list of repositories Blathers can access. This URL will start with an account picker, please make sure to select your username to find you fork.

Now you are ready to use Blathers for backports. There are two ways to do this via labels or comments.

Labels

Upon merge, Blathers will automatically attempt to create backport PRs for each branch that was indicated via a backport label on your PR, i.e. backport-25.1. Optionally you can use backport-alllabel to have Blathers automatically backport to all supported release branches.

If any of the backport PRs fail, Blathers will post a comment on the original PR with details and add a backport-failed label to the original PR.

Automatic backport can fail for a few reasons, such as:

...

If this happens, you must use the manual method (the backport command-line tool) described below.

...

Comments

You can ask Blathers to create a backport PR without using the tagging system and waiting for merge by commenting on a PR, with the following syntax:

...

Blathers will then immediately carry out the backports just as it would when it detects a merged PR with backport tags.

Blathers additionally supports blathers backport all command to backport to all supported branches.

Manual Method with the backport CLI tool

...