For Developers‎ > ‎

Contributing Code

This page covers contributing code to the main Chromium repository. It assumes you already have a working checkout and build. A full checkout pulls many other repositories such as v8 and Skia which have their own repositories and processes. Chromium it itself pulled into ChromiumOS which has its own process.

Related resources

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.
  • 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.
  • Keep in mind that just because there is a bug in the bug system doesn't necessarily mean that a patch would be accepted.

Legal stuff

Create a local branch

Start with a branch in git. Here we create a branch called mychange (use whatever name you want here) based off of the origin/master branch (the upstream repository):

git checkout -b mychange origin/master

Write and test your code.

  • Conform to the style guidelines.
  • Include appropriate unit tests.
  • Patches should be a reasonable size to review. Giant patches are unlikely to get reviewed quickly.

Commit your patch locally in git (you may want to do search for git tutorials if you are unfamiliar with it).

git commit -a

Uploading a change for review

Initial git setup

Authenticate with depot tools - make sure to authenticate with your @chromium.org account:

depot-tools-auth login https://codereview.chromium.org

Tell git about your name, email and some other settings.
git config --global user.name "My Name"
git config --global user.email "myemail@chromium.org"
git config --global core.autocrlf false
git config --global core.filemode false
git config --global branch.autosetuprebase always
The upload command

We use the Rietveld code review tool running at codereview.chromium.org. To upload your change to Reitveld, use the git-cl tool that came with depot_tools when you checked the code out.git cl upload

This will create a Reitveld "issue" for you. You will be prompted for a description, and some presumbit checks will also be run to identify common errors. When it is done it will print the URL you can use to see the change on the web.

Writing change list descriptions

Use the following 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.

Long lines should be wrapped to 80 columns for easier log message viewing in
terminals.

BUG=123456

Use the bug number from the issue tracker (see more on bug formatting).

You can optionally include your code reviewer at the bottom (this saves you from having to type it into the web UI):

R=foo@chromium.org

If there are instructions for testers to verify your change is correct, append:

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

Code review

Finding 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 git blame for the file and the OWNERS files.

  • Anybody can review code, but there must be at least one owner for each directory you are touching.
  • If you have multiple reviewers, make it clear in the message you send requesting review what you expect from each reviewer. Otherwise people might assume their input is not required or waste time with redundant reviews.
  • The git cl owners command can help find owners.

Requesting review

Open the change on the web (if you can't find the link, run git cl issue to see the issue for your current branch, or go to the Web UI codereview.chromium.org, log in, and look at "Unsent Issues/Outgoing").

Reviewers expect to review code that compiles and passes tests. If you have access, now is a good time to run your change through the automates tests (see below).

Click Edit Issue in the upper-left (if you don't see this link, make sure you are logged in). In the Reviewers field, enter a comma-separated list of the reviewers you picked, and press Update Issue.

Click Publish+Mail Comments in the upper-left (never mind that you have no comments to publish). This will send email to notify the reviewers you are requesting a review. If you have any particular questions or instructions for the code review, enter them in the Message box, but it's fine to leave this field empty. Click Publish all my drafts (never mind that you have no drafts to publish).

The review process

Reviewers try to review code that conforms to the 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 in the code or answer questions in the code review tool. Update the patch set in the issue by re-running git cl upload and doing Publish+Mail Comments again in the tool.

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) 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 (see owners guidelines), you can instead list the OWNERS as "TBR" ("To Be Reviewed") for review after commit. Add the reviewers addresses to a line at the bottom of the change description TBR=foo@chromium.org, and be sure to also add them as reviewers in the code review tool and send mail.


Running automated tests

Before being submitted, a change must pass a large series of compilations and tests across many platforms. To trigger this process, press the CQ dry run (CQ = "Commit Queue") at the bottom of the patch summary in the code review tool. This link is only available to those with permission:

  • If you have an @chromium.org email address, request try job access for yourself.
  • If you've made a few patches you can request a reviewer to nominate you for try job access.
  • Otherwise, write in the code review request message that this is your first patch and request try jobs be run for you.

Committing

Changes should generally be committed via the commit queue. This is done by checking the Commit check box below the patch in the code review tool. The commit queue will then send your patch to the try bots, which will eventually appear as colored bubbles near the checkbox in the code review tool (the same thing that happens for dry runs). 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. Sometimes a test might be flaky, if you have an isolated failure that appears unrelated to your change, wait a while and click commit again.

Alternatively, it is possible to directly commit your change, bypassing the commit queue. This should only be used in emergencies because it will bypass the tests.


Tips

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) when there are no outstanding comments. Then upload another patch with your changes. This way the reviewer can see what changes you made independent of the rebase.

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.