Directly committing code

When contributing code to Chromium, the last step in the life of a change list is committing it, after which it's closed.

The preferred way of committing changes is via the commit queue.

However, in certain circumstances it is acceptable or necessary to directly commit your change, bypassing the commit queue. This is discouraged however, due to not running the tests (hence higher risk of breakage), and requires more supervision on the part of the committer.
Generally directly committing should only be done if the CQ itself is broken, or the CL cannot be processed by the CQ.

If you wish to skip the tree status checks, but otherwise use the CQ, you can use NOTREECHECKS=true in the Rietveld issue description, though this is obviously strongly discouraged. The primary use case is if the tree is closed due to some breakage, and you wish to commit a change that will fix the breakage.
NOTRY and NOTREECHECKS are flags for the CQ: you still commit by clicking the "Commit" box.

In a nutshell:
  • Before:
    • Have the change reviewed per usual process contributing code, with an issue and description on Rietveld, and sufficient LGTMs or TBRs (since presubmit OWNERS approval test isn't run when dcommitting).
    • Run tests manually, both locally and using the try server for other platforms, to reduce risk of breakage (since try jobs aren't run when dcommitting). Try jobs can be run individually via Rietveld, while the standard set can be run from the command line via git try.
    • Join the #chromium IRC channel, so that sheriffs can notify you of possible breakages.
    • Check that the tree is open (green): Chromium Tree Status :: Blink Tree Status
  • During:
    • Double-check that the tree is open.
    • Commit as per below, preferably using git-cl.
  • After:
    • See if there are any immediate messages on IRC.
    • Stay on IRC for an hour or so in case anything happen afterwards.
In case of emergencies, please remember to at least:
  • Create a Rietveld issue for description and reference.
  • List OWNERS in TBR (assuming no time for review).
  • Join IRC, explain what's happening, and make sure there are no immediate objections.
Tree closure: If the most recent set of changes to the repository breaks the build, we say the tree is red, or closed. You cannot check in your changes until it is green again. You can check the status via apps at Chromium Tree Status or Blink Tree Status. More low-level, you can check the BuildBot waterfalls (Chromium | Chromium OS) to see that the columns are mostly green before checking in your changes. Otherwise, you will not know if your changes break the build or not.

Reasons

Good reasons to dcommit code:
  • You are reverting at previous change that broke the build (so the tree is closed) and the CQ is down – if the CQ is up, please use NOTRY and NOTREECHECKS instead.
  • The change can't be processed by the commit queue (see Build-CommitQueue bugs), such as changing file permissions (Issue 162196).
Marginal reasons to dcommit code:
  • A presubmit script is failing.
    • If the failure is a false positive, if at all possible, please fix the script instead.
  • The change is very big (e.g., large-scale formatting changes or renaming), so by the time it's finished uploading to Rietveld the patch is out of date and won't apply when the CQ tries it.
    • If at all possible, try breaking up the patch and landing normally. Even innocuous-looking changes can cause breakages.
Bad reasons to dcommit code:
  • The commit queue is too slow (unless the slowness means the change is out of date by the time it is processed) – please be patient.
  • The commit queue is down or stalled – please be patient.
  • The tree is closed but you want to commit it anyway – please wait for tree to reopen, or use NOTREECHECKS=true if the CL needs to be committed while the tree is closed.

Commands

git cl land (for git repos)

git cl land
This command commits the current changelist via git directly. You should use this command if you are in a real git repo, such as the chromium repo. You can pass --bypass-hooks if something is wrong with the presubmit hooks or they are blocking an emergency submit.

git cl dcommit (for svn repos)

For ChromiumOS:
git cl push

In more detail:
# Sync branch to ToT
git pull --rebase origin master
git rebase master my_feature_branch
gclient sync
# Update git-svn data with ToT
git fetch origin
git svn fetch
# Actually commit
git cl dcommit

dcommit

git cl dcommit is lower-level and pickier than the commit queue; you need to have git-svn data set up, and your branch needs to be up-to-date with ToT. This command is only used for svn repositories.

If your checkout was created by fetch, it should have the git-svn data set up. If it wasn't, or if it was created by fetch --nosvn=True, set up the git-svn metadata by running:
git svn init --prefix=origin/ -T trunk/src svn://svn.chromium.org/chrome
git config --replace svn-remote.svn.fetch trunk/src:refs/remotes/origin/git-svn
git fetch origin
git svn fetch

Sync branch with ToT:
git pull --rebase origin master
git rebase master my_feature_branch
gclient sync

Update git-svn data with ToT:
git fetch origin  # Optional, makes next step faster
git svn fetch  # Ensure your svn data is up-to-date with ToT

Troubleshooting dcommit

Sometimes dcommit fails, primarily due to SVN metadata being out of date or corrupted (e.g., if git cl is interrupted during a dcommit). Symptoms include it trying to refetch commits you've already fetched, or printing "Transaction is out of date" errors on unrelated files. This can be fixed by updating or rebuilding SVN metadata, which does not require any changes to your local git repository itself (outside of the SVN metadata).

If the metadata is just out of date, this updates it:
cd "$CHROMIUM_DIR"  # or $BLINK_DIR or other repository root
git fetch origin
git svn fetch

If the metadata is corrupt, this deletes it and rebuilds it:
cd "$CHROMIUM_DIR" && rm -rf .git/svn   # clobber git-svn metadata
git svn find-rev r1   # run a no-op command to rebuild metadata

If you get the following error:
Can't guess svn branch -- try specifying it on the command line
...then you probably need to re-run the git-svn setup steps correctly on the master branch, and then create a new branch. See Get the Code for git-svn setup details.

svn dcommit

It is also possible to use svn dcommit, but this does not integrate with Rietveld (e.g., it uses your local git commit log as the commit message) and is discouraged, generally being reserved for emergencies.

Committing a patch for a non-committer

First check that the non-committer has signed the CLA/CCLA and are listed in the AUTHORS and CL Description.
  • If you use git
    • git cl patch <code review issue number>
      • This command will download the patch from the code review website, apply the patch, and set the issue number.
    • If you work on chrome:
      • git cl try  # and wait for green bots
      • git cl dcommit -c 'Joe Noncommiter <[email protected]>'
    • If you work on chromeos:
      • git commit --amend -s --author="$AUTHOR_NAME <$AUTHOR_EMAIL>"
      • git cl push -c
    • You're done!
  • If you use subversion / gcl
    • Really, try to use git cl patch if possible.
    • You need to apply the patch locally with curl http://... | patch -p0
    • Recreate a CL with gcl change foo
    • Edit .svn/gcl_info/changes/foo and change the first 0 for the code review number
    • gcl commit foo

Committing to Blink

To dcommit to the Blink repo you will need to set up git-svn metadata in third_party/WebKit.  (This is not done automatically by 'fetch blink'.)

cd third_party/WebKit
git svn init --prefix=origin/ -T trunk svn://svn.chromium.org/blink
git config --replace svn-remote.svn.fetch trunk:refs/remotes/origin/master
git fetch origin
git svn fetch

Once this is set up, you can use git cl dcommit as described above.

Comments