All development starts on the
In most cases, to add a commit to a patch release (or a beta/rc after a release branch has been created), you should submit a PR to
master first and get it reviewed and merged there.
PRs should be eligible for backport if you would like to backport them.
Tag your PR with one or more of the
backport labels (like
backport-21.1.x, for the 21.1 release) to indicate that it should be backported once merged on master.
“Must check” for reviewers of backport PRs
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
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 will automatically backport PRs with backport tags
Upon merge, Blathers will automatically attempt to create backport PRs for each branch that was indicated via a
backport label on your PR.
If any of the backport PRs fail, Blathers will post a comment on the original PR with details.
Automatic backport can fail for a few reasons, such as:
backport branch already exists for a PR
backport has merge conflicts
backport branch contains merge commits, which are not allowed in backports
If this happens, you must use the manual method (the
backport command-line tool) described below.
Blathers can be instructed to try to backport a PR with a comment
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 backport <branch1> <branch2> …
For example, to backport a PR to 21.1 and 20.2, you would add a comment on the PR that says:
blathers backport 21.1 20.2
Blathers will then immediately carry out the backports just as it would when it detects a merged PR with backport tags.
Manual Method with the backport CLI tool
If Blathers was unable to automatically create a backport PR, follow these steps after the main PR is merged to cherry-pick it into the release branch.
Make sure the
backporttool is installed:
go install github.com/benesch/backport@latest
For first time setup, you will need to set the
cockroach.remotegit config option. If your fork of cockroach is in the remote named
origin, then set it with
git config cockroach.remote originwhile in your local cockroach git repo.
backport -r VV.V xxxxx, where
VV.Vis replaced by the version number of the release branch and
xxxxxis replaced by the GitHub PR number of the PR you are trying to backport, or a space-separated list of PR numbers.
This will automatically create a backport branch and upload it to your repository against the release branch to GitHub.
Then, it will try to open your browser to create a new PR with that branch, or provide instruction on how to do this manually if it cannot open your browser.
If there were merge conflicts,
backportwill halt and ask you to fix them. Once they're fixed, run
backport --continueto continue the procedure.
If there were any non-trivial merge conflicts, be sure to call those out in the PR message so reviewers can pay closer attention to the diff.
If something goes wrong, you can use
backport --abortto give up on the current manual backport.
Note: You do not need to use bors to merge a backport PR; just hit the big green button once the CI is green and the backport is approved by the reviewer (usually the main reviewer of the original PR to