Contributing Code

Quick links

Other sites

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‎ > ‎

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. 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).

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 (Chromium | Chromium OS) 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 (Chromium | Chromium OS) and describe what you're doing if there isn't one already.

Get your code ready

Code

must conform to the Chromium style guidelines.
must be tested, preferably with unit tests.
should be a reasonable size to review. Giant patches are unlikely to get reviewed quickly.

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.
Legal

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.
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).
NOTE TO REVIEWERS: Follow the External Contributor Checklist.

Review Tools

You either use gcl or git-cl but not both. Both gcl and git-cl comes with depot tools.

Inside a subversion checkout, you need to use gcl. This is the case by default for a chromium checkout. See UsingGit if you want to use git.
Inside a git checkout, you need to use "git cl". This is the case by default for a chromiumos checkout. For help, run git cl help

Life of a Change list

Create a change list (CL)

GCL

Run gcl help for some doc.

Make a changelist with the gcl change command . The changelist name is only to help you refer to it on your local computer, so call it whatever you want:

C:\code\src\chromium\src> gcl change mychange

This will open your text editor. Write the change description at the top of the file. The description should describe what your patch changes and why. This is important for people who are looking at commit logs in the future to track down an issue: they should be able to see why you changed it without going anywhere else. If there's an associated bug file, you should also add a BUG=bug_number line so they can find the associated bug. If you have manual test instructions that you want to pass to the test team so that they can validate the fix, add TEST=how_test_test at the end of the description. If there is no bug or test, leave out the lines. Multiple bugs can be listed, comma separated. Example:

Increase the goat teleporter timeout threshold to 100 because the old

value of 10 caused problems for extremely overweight goats. Tests show

that the largest goat in existence should be teleported in 50ms, so...

BUG=31337,2754

TEST=Try loading an overweight goat and confirm the teleporter works.

NOTE: "BUG=xxx" will update the bug in the default issue tracker for the repository you're committing to. That means if you're checking into the chromium-os repository, the bug is assumed to be a chromium-os bug number, and if the chrome repository, a chrome bug number. If this isn't right, you can preface each bug number with chromium: or chromium-os: as appropriate to cause the correct bug to be updated. (Failing to do this will lead to very confused engineers who get the wrong bug mailed to them.)

Broken frame code in Chrome led to black holes spontaneously appearing in ChromeOS devices.

BUG=chromium-os:1234

TEST=The world is not converted to a small supermassive point on startup.

Cut and paste the filenames above or below the divider to add files to or remove files from the changelist. You can use the gcl opened command to see your changed files and changelists:

C:\code\src\chromium\src> gcl opened

M chrome\browser\browser.vcproj ← this is a modified file not in any changelist

--- Changelist mychange:

M chrome\browser\browser.cc

GIT 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.

GCL

Use the gcl upload command:

C:\code\src\chromium\src> gcl upload mychange

Issue created. URL: http://codereview.chromium.org/123456

Uploading chrome\browser\browser.cc (1/1)

You may have to enter a Google Account username and password, for example your Gmail credentials but it's not required to be a Gmail account. The URL it gives you is the page where the review can be accessed. If you want to upload a new copy of your patch, optionally add or remove files using gcl change and upload it again using the same gcl upload command.

Once you've uploaded your change and know its patch URL, add that to the bug comments. That way someone coming along later can make comments or see how the bug was fixed.

GIT CL

Use the git cl upload command:

git cl upload

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.

GCL

Add any new files that need to be added to your checkout

gcl change changelist_name

gcl upload changelist_name

GIT CL

If you need to update code 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"). When the reviewer is happy with your patch, they will say "LGTM" ("Looks Good To Me").

Note: As you work through the review process, both you and your reviewers should converse using the code review interface, and send notes using Publish+Mail Comments. Avoid the temptation to respond directly to review mails (or, for reviewers, to send review comments) directly from your email client; doing that won't add your comments to the online record for the issue under review, and can make it hard for others to understand later what the history of a patch was.

Check in your changes

GCL

gcl commit changelist_name

Resist the temptation to just run svn commit, since (a) this will by default submit everything modified and not just your changelist, and (b) gcl commit will automatically create a log message based on your issue description. The descriptions are very important for tracking which bugs were fixed and why a certain change was made.

GIT CL

git cl will squash all your commits into a single one with the description you used when you uploaded your change.

Pushing your change

For Chromium:

git cl dcommit

For ChromiumOS:

git cl push

If you are not a committer yet

You need to explicitly request the reviewer to commit for you. You should add "Contributed by me@example.com" in your change description.

Alternatively, in the Reitveld issue, there is a "commit" check box. If you check that, it will send your patch to the build bots, and if all platforms pass, your change will be auto committed. If it fails, check the logs from the buildbot failure. You can find the logs by searching 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.

Instructions for Reviewer: Checking-in the patch for a non-committer

If this is the first patch from a contributor, make sure the contributor has signed the CLA or CCLA and the patch adds the right name to the AUTHORS file.
Make sure the description includes the committer's name. For example: "Add cool feature x.\n\nPatch from First Last <email@example.com>\nBUG=123"
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 try # and wait for green bots
git cl dcommit -c 'Joe Noncommiter <hackosaurus@hotmail.com>'

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

Look out for breakage or regressions

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. 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.

Please be available via the chromium IRC channel when landing changes so that sheriffs may notify you of possible breakages.

Hint: Use the try server.