For Developers‎ > ‎How-Tos‎ > ‎

How to use merge a change to a release branch

This applies to commits to Chromium repository branches. For changes to Chromium OS repositories, see the information here; for Blink, see experimental branches.

When to merge?

Please read the Merge Request Process and The Zen of Merge Requests for more details on when we merge changes to release branches, and how to request a merge.

This document assumes you've already landed your change on the master branch, you've already requested a merge (via the Merge-Request-XX label, where XX is the milestone), and you've already received approval to merge onto a particular release branch from a TPM (via the Merge-Approved-XX label).

Merging to a branch and don't know the branch number? The TPM (release manager) approving the merge will have it, and it's typically sent out in an email after every branch.

Once you have approval, you know your branch number, and you're ready to merge there are three ways to merge a change.

(1) The easiest way: using Gerrit to cherry-pick CLs

You can use Gerrit to cherry-pick CLs directly to our release branches where no conflicts are present (if there are merge conflicts, use the Git Drover instructions below), no terminal required!  To do so, follow the steps below once you have merge approval:

Press the "More" button and select "Cherry Pick"


Enter branch details. For Chromium, use:

 M67 refs/branch-heads/3396
 M68 refs/branch-heads/3440
 M69 refs/branch-heads/3497
 M70 refs/branch-heads/3538



Voila, you now have a fresh CL uploaded for the branch - simply +1 and commit (or go through review where you'd like). NOTE: non-committers will need a +2 from a committer to complete the merge.

After merging to a release branch, try to watch http://go/stablebuilders (for stable branches) and http://go/betabuilders (for beta branches) and here for dev/trunk branches to make sure everything's all right.

(2) The second-easiest way: Git Drover (from the command line)

Drover is a command-line tool, included with depot tools, that allows developers (committers) to rapidly merge and revert changes on our trunk/branches without any previously checked out working copy. A typical drover command to merge or revert with no conflicts takes about 1 minute to run from start to finish.

NOTE: Using Gerrit (as described above) will almost certainly be faster than using git-drover, we recommend trying it first.

git-drover is a new drover for working with git repositories. It is not:
  • The way to do all merges/reverts in the "post git migration" world.
  • If you are working with a repository that is still svn-based, see the old SVN Drover instructions below.
  • The way to do anything that is not a merge of a git commit (e.g. DEPS rolls).
  • Those changes should follow the normal commit workflow, or use other tools made for the job (e.g. roll-dep)

Requirements/ recommendations

  • Note that these instructions assume you have a working depot_tools and chromium checkout as described in the depot_tools tutorial.
  • You'll need your git (.gitcookies) credentials.
  • You'll also need your chromium.org credentials (for code reviews).
  • Before working with branches, you must gclient sync --with_branch_heads at least once to fetch the branches.

Usage

  • Merge a change to a release branch
    • git drover --branch <branch_id> --cherry-pick <revision> (e.g. git drover --branch 9999 --cherry-pick b5a049)
For merges on Windows and reverts, please see man git-drover or the online git-drover doc for instructions to achieve equivalent functionality using other git and depot_tools commands.

Troubleshooting

Cannot find 'refs/branch-heads/9999'

Follow the steps for checking out a release branch to sync the branch heads.

Not in chromium-committers Gerrit group

If this is the first time you've tried to merge into a branch, you may run into the following error when trying to git cl land the change:
error: failed to push some refs to 'https://chromium.googlesource.com/a/chromium/src.git'
ERROR:git-retry:Process failure was not known to be transient; terminating with return code 1
Push failed with exit code 1.
To https://chromium.googlesource.com/a/chromium/src.git
! HEAD:refs/pending/branch-heads/2311 [remote rejected] (prohibited by Gerrit)

If you see this error, and you are a committer (went through the process described here) you may not have been added to the chromium-committers gerrit group yet (the group update process lags behind a bit). File a bug with the Infra-Git label, so you can be added to the group manually.

Uploading merge CL after manual edit

If you've started merge with "git drover" and made any manual edit, "git cl upload" doesn't work to upload the new snapshot. Use "git drover --continue".

Build failure may be due to DEPS changes

NOTE: This only applies to branches prior to 3420. After 3420, DEPS file on branches are valid and represent the true branch dependencies. DO NOT merge from the release DEPS after branch 3420.

If the merged branch doesn't build locally, you may need to port DEPS change from the version-number named branch (e.g. https://chromium.googlesource.com/chromium/src.git/+/53.0.2785.24). DEPS changes after branch cut are not made on the release branch but in the version-number named branches.

Check which branches your patch has been merged to

If you have a patch and want to check which branches it has been merged to, or which version it first got released in, you can use:
$ git find-releases eeac3e6a187e362d796fa01489927e773be705ac
commit eeac3e6a187e362d796fa01489927e773be705ac was:
  initially in 55.0.2867.0
  merged to 54.0.2840.36 (as 72308707baae9aac0bea97387c1b4426bd378f51)

Re-merging patch on Release Branch

When the initial merge attempt fails, cherry-picking the CL again with "git drover" might not work anymore with the following error message:
! [remote rejected] .... (change https://chromium-review.googlesource.com/99999 closed)
 
This can be solved by removing the entire line of "Change-Id: ..." field in the commit log. Gerrit will bypass the checking on "Change-Id" and will let you submit the cherry-pick CL.

(3) The manual way: Check out a release branch and cherry-pick

This isn't any harder, it can just take longer because you have to check out the whole release branch. This can be a good approach if your patch has a lot of merge conflicts or you have to deal with file renames, or if you just need to check out the release branch in order to compile and test your change because the merge was tricky.

The first step is to make sure that you have branch heads:

$ gclient sync --with_branch_heads

Also ensure that your git repository is up-to-date:

$ git fetch

Now, create a new branch from the top of the branch-head. Replace my_branch_name with a name for the branch, and BRANCH with the branch number you got from the TPM (see above).

$ git checkout -b my_branch_name branch-heads/BRANCH

Next, cherry-pick the change you want to land, using the hash of the commit you want to pick from the master branch:

$ git cherry-pick -x HASH_OF_THE_COMMIT_FROM_MASTER

At this point, resolve any conflicts if necessary, and use git cherry-pick --continue if prompted to do so. Optionally run "gclient sync" and use ninja to build and test to make sure your patch worked.

Now upload the change for review. You should edit the change description to say something like "Merge to release branch" at the top or something like that, to make it easier for your reviewers to distinguish this change from the original patch. You can also add a TBR=username@chromium.org like for "to be reviewed", as it's not mandatory to get code review again before merging to a release branch. (Use your best judgement.)

$ git cl upload

You can now use Gerrit to self-review and submit, or you can land directly from the command-line like this:

$ git cl land --bypass-hooks

Comments