The Chromium Projects

Search this site

Except as otherwise noted, the content of this page is licensed under a Creative Commons Attribution 2.5 license, and examples are licensed under the BSD License.
For Developers‎ > ‎

Contributing Code

If you want to contribute code to Chromium, there are a few things you can do to make the process flow smoothly.  For Chromium OS, please go here.

Quick start guide: Life of a Chromium Developer

Note: These instructions apply only if your changes are in Chromium code. If your changes are in a directory that we pull from another repository (e.g. Blink, v8, skia, gtest, gmock), you need to use that project's way of getting code submitted. For example, here is a cheatsheet for contributing to Blink, and here's Chrome DevTools. Once your change has landed upstream, you need to update Chromium's DEPS file to pull in the new revision (we update Blink very often, so you don't have to take care of this if you're contributing to Blink).

Contents

  1. 1 Communicate
  2. 2 Get your code ready
  3. 3 Review Tools
  4. 4 Life of a Change list
    1. 4.1 Create a change list (CL)
    2. 4.2 Upload your change to Rietveld
      1. 4.2.1 Change List Description Structured Elements
    3. 4.3 Request review
      1. 4.3.1 Find a reviewer
      2. 4.3.2 The review process
      3. 4.3.3 Some review tips
    4. 4.4 Approval
    5. 4.5 Committing changes
      1. 4.5.1 Committing a patch for a non-committer
      2. 4.5.2 See also
  5. 5 Experimental branches

Communicate

  • Whether you're writing a new feature or fixing an existing bug, it pays to get a second opinion before you get too far. If it's a new feature idea, post to the appropriate discussion group (Chromium | Chromium OS) and propose it.  If it is in the existing code base, it is a good idea to talk to some of the folks in the OWNERS file for the code you want to change.
    Start by looking for an OWNERS file in the directory of the file you wish to change, then keep moving up the tree until you find one.
  • Not all bugs in our bug system are assigned, but if the one you're interested in fixing is, send a note to the person it's assigned to and ask if they would like a patch.
  • Behavior changes and anything nontrivial (i.e. anything other than simple cleanups and style fixes) should generally be tracked in the bug system. Please file a bug and describe what you're doing if there isn't one already.

Get your code ready

  1. Code
    1. must conform to the Chromium style guidelines.
    2. must be tested, preferably with unit tests.
    3. should be a reasonable size to review. Giant patches are unlikely to get reviewed quickly.
  2. Run the unit tests and the UI tests to make sure you haven't broken anything. You can ask someone to pass it to the try server.
  3. Legal
    1. You must complete the Individual Contributor License Agreement. You can do this online, and it only takes a minute. If you are contributing on behalf of a corporation, you must fill out the Corporate Contributor License Agreement and send it to us as described on that page.
    2. If you've never submitted code before, you must add your (or your organization's) name and contact info to the AUTHORS file (Chromium | Chromium OS).
    3. NOTE TO REVIEWERS: Follow the External Contributor Checklist.

Review Tools

Please use git-cl from depot tools. For help, run git cl help.

Life of a Change list

Create a change list (CL)

Creating a change in git is really just creating a branch.

git checkout -b mychange origin/master
echo "This describes the goat teleporter." > GOATS
git add GOATS
git commit

Upload your change to Rietveld

Rietveld is the open source code review tool we use. We use an AppEngine instance at http://codereview.chromium.org.

Use the git cl upload command:

git cl upload --send-mail

Change List Description Structured Elements

CL descriptions follow the form:

Summary of change.

Longer description of change addressing as appropriate: why the change is made, context if it is part of many changes, description of previous behavior and newly introduced differences, etc.

BUG=123456

The issue number from the issue tracker

NOTRY=true

The commit queue will skip using try jobs.

R=foo@chromium.org

Can be specified when creating the CL and using git cl upload --send-mail will send emails directly without visiting the web UI.

TEST=Load example.com/page.html a click the foo-button; see crbug.com/123456#c12 for more details.

Optional line providing guidance to humans who verify changes in builds. Refer to a comment on an issue with reproduction steps, or if manual steps are brief simply state them here.

Request review

Go to the supplied URL or just go to the respective code review page (Chromium | Chromium OS) and click Issues created by me.  Select the change you want to submit for review and click Edit Issue.  Enter at least one reviewer's email address and click Update Issue.  Now click on Publish+Mail Comments, add any optional notes, and send your change off for review. All Chromium code reviews are automatically cc'd to their respective review groups, so that everyone has an opportunity to see and comment on the changes being made.

Note: If you don't see editing commands on the review page, click Log In in the upper right.
Hint: You can add -r reviewer@example.com --send-mail to send the email directly when uploading a change in both gcl and git-cl.

Find a reviewer

Ideally, the reviewer is someone who is familiar with the area of code you are touching. If you have doubts, look at the svn blame or git blame for the file to see who else has been editing it. Failing that, ask on #chromium or #chromium-os on irc.freenode.net. You can also just request review from the respective lists (Chromium | Chromium OS), but more specific review requests will be attended to sooner.  Your review must include one person from the OWNERS file for every directory you change code in.  

The review process

Chromium and Chromium OS reviewers try to review code that conforms to these guidelines as quickly as possible. You should hear back within 24-48 hours. Remember though, if you submit a giant patch, or do a bunch of work without discussing it with the relevant people, you may have a hard time convincing anyone to review it! Speak with others early and often. Sometimes, the tree will be locked down and certain types of changes won't be allowed. This is true when we're preparing a release. During times like these, reviewers may be focused on fixing the bugs required to get the release out the door.

Remember that code reviews are an important part of the engineering process. The reviewer will almost always have suggestions or style fixes for you, and it's important not to take such suggestions personally or as a commentary on your abilities or ideas. This is a process where we work together to make sure that the highest quality code gets submitted!

You will likely get email back from the reviewer with comments. Fix these and update the patch set in the issue by uploading again.  The upload will explain that it is updating the current CL and ask you for a message explaining the change.

Important: during the lifetime of a review you may want to rebase your change onto a newer source revision to minimize eventual merge pain.  The reviewer-friendly way to do this is to upload the rebase as its own patchset (with no changes other than the rebase), and to only do this when there are no outstanding comments.  In other words, address all the comments from the latest patchset (A), upload a new patchset (B) containing those updates, and only then rebase and upload a patchset (C).  This way your reviewer can view the A/B diff to see all the changes that resulted from the last round of review, and can view the B/C diff to ensure only rebase-related changes were introduced.  Doing things differently (addressing comments and rebasing in a single patchset, or rebasing first and then addressing comments) makes things harder than necessary for your reviewer.

If you need to update the code on an already uploaded CL, simply edit the code, commit it again locally, and then run git cl upload again e.g.

echo '' >> GOATS
git add GOATS
git commit -m 'add newline fix to GOATS'
git cl upload

Once you're ready for another review, use Publish+Mail Comments again to send another notification (you can say something like "new snapshot uploaded" or PTAL "Please Take A/Another Look").

Some review tips

As you work through the review process, you and your reviewer(s) should converse using the code review interface, sending notes using Publish+Mail Comments.  Avoid the temptation to respond to review e-mail directly from your email client; doing that won't add your comments to the online record for the issue under review, making it hard for others to later understand the patch history.

Code authors and reviewers should keep in mind that Chromium is a global project -- contributors and reviewers are often in time zones far apart. Please read these guidelines on minimizing review lag and take them in consideration both when writing reviews and responding to review feedback.

Approval

When the reviewer is happy with your patch, they will say "LGTM" ("Looks Good To Me"). The reviewer types this exact text (case-insensitive, so "lgtm" also works) in their comment, which is detected by Rietveld and marks approval. If this is accidentally typed, writing "not LGTM" withdraws approval.

Except in rare cases, you need approval from OWNERS of all affected files before committing.
In specific cases where it is allowed, you can instead list the OWNERS in the TBR= "To Be Reviewed" field of the CL description, and they will review it after it has been committed. See the OWNERS guidelines for discussion of when it is acceptable to TBR an OWNER.

Committing changes

The preferred way of committing changes is via the commit queue. This is done by checking the "commit" check box in Rietveld, or from the command line via git cl set_commit. The commit queue will then send your patch to the try bots, which will eventually appear as bubbles on the Rietveld issue. If all tests pass, your change will be auto committed. If it fails, click on the red (failure) bubbles for a direct link to the failures. Alternatively, search the waterfall for your changelist number and clicking into the links where I see the red failure blocks. If the failure appears unrelated to your change, it is OK to check the commit check box again and retry; sometimes the tests or bots are flaky.

Alternatively, it is possible to directly commit your change, bypassing the commit queue. This is discouraged, due to not running the tests, and requires more supervision on the part of the committer, but is acceptable or necessary in certain circumstances. Only committers can commit changes. If you are not a committer, you should try to commit via the commit queue first. If that doesn't work for some reason, ask your reviewer to commit it for you, and add "Contributed by me@example.com" in your change description for clarity.

Committing a patch for a non-committer

See also

Experimental branches

Most contributions consist of individual patch sets (change lists), which are reviewed and processed through Rietveld. For more complex situations, one can use a remote git branch on the writable git repository; this allows one to use git push and collaborate or just post code dumps. See [blink-dev] A writable git repo for collaboration and code dumps for details. (Blink) branches should be pushed to: https://chromium.googlesource.com/experimental/chromium/blink.