This page describes the full process of submitting a patch to the AOSP, including reviewing and tracking changes with Gerrit.

Prerequisites

• Before you follow the instructions on this page, you need to initialize your build environment, download the source, create a password, and follow the instructions on the password generator page.

• For details about Repo and Git, see the Developing section.

• For information about the different roles you can play within the Android Open Source community, see Project roles.

• If you plan to contribute code to the Android platform, be sure to read the AOSP's licensing information.

• Note that changes to some of the upstream projects used by Android should be made directly to that project, as described in Upstream Projects.

For contributors

Authenticate with the server

Before you can upload to Gerrit, you need to establish a password that will identify you with the server. Follow the instructions on the password generator page. You need to do this only once. See Using Authentication for additional details.

Start a repo branch

For each change you intend to make, start a new branch within the relevant git repository:

repo start NAME .

You can start several independent branches at the same time in the same repository. The branch NAME is local to your workspace and will not be included on Gerrit or the final source tree.

Make your change

Once you have modified the source files (and validated them, please) commit the changes to your local repository:

git add -A
git commit -s

Provide a detailed description of the change in your commit message. This description will be pushed to the public AOSP repository, so please follow our guidelines for writing changelist descriptions:

• Start with a one-line summary (50 characters maximum), followed by a blank line. This format is used by git and Gerrit for various displays.

• Starting on the third line, enter a longer description, which must hard-wrap at 72 characters maximum. This description should focus on what issue the change solves, and how it solves it. The second part is somewhat optional when implementing new features, though desirable.

• Include a brief note of any assumptions or background information that may be important when another contributor works on this feature next year.

Here is an example commit message:

short description on first line

more detailed description of your patch,
which is likely to take up multiple lines.

A unique change ID and your name and email as provided during repo init will be automatically added to your commit message.

Upload to Gerrit

Once you have committed your change to your personal history, upload it to Gerrit with

repo upload

If you have started multiple branches in the same repository, you will be prompted to select which one(s) to upload.

After a successful upload, repo will provide you the URL of a new page on Gerrit. Visit this link to view your patch on the review server, add comments, or request specific reviewers for your patch.

Uploading a replacement patch

Suppose a reviewer has looked at your patch and requested a small modification. You can amend your commit within git, which will result in a new patch on Gerrit with the same change ID as the original.

git add -A
git commit --amend

When you upload the amended patch, it will replace the original on Gerrit and in your local git history.

Resolving sync conflicts

If other patches are submitted to the source tree that conflict with yours, you will need to rebase your patch on top of the new HEAD of the source repository. The easy way to do this is to run

repo sync

This command first fetches the updates from the source server, then attempts to automatically rebase your HEAD onto the new remote HEAD.

If the automatic rebase is unsuccessful, you will have to perform a manual rebase.

repo rebase

Using git mergetool may help you deal with the rebase conflict. Once you have successfully merged the conflicting files,

git rebase --continue

After either automatic or manual rebase is complete, run repo upload to submit your rebased patch.

After a submission is approved

After a submission makes it through the review and verification process, Gerrit automatically merges the change into the public repository. Other users will be able to run repo sync to pull the update into their local client.

Upstream Projects

Android makes use of a number of other open source projects, such as the Linux kernel and WebKit, as described in Codelines, Branches, and Releases. For most projects under external/, changes should be made upstream and then the Android maintainers informed of the new upstream release containing these changes. It may also be useful to upload patches that move us to track a new upstream release, though these can be difficult changes to make if the project is widely used within Android like most of the larger ones mentioned below, where we tend to upgrade with every release.

One interesting special case is bionic. Much of the code there is from BSD, so unless the change is to code that's new to bionic, we'd much rather see an upstream fix and then pull a whole new file from the appropriate BSD. (Sadly we have quite a mix of different BSDs at the moment, but we hope to address that in future, and get into a position where we track upstream much more closely.)

ICU4C

All changes to the ICU4C project at external/icu4c should be made upstream at icu-project.org/. See Submitting ICU Bugs and Feature Requests for more.

LLVM/Clang/Compiler-rt

All changes to LLVM-related projects (external/clang, external/compiler-rt, external/llvm) should be made upstream at llvm.org/.

mksh

All changes to the MirBSD Korn Shell project at external/mksh should be made upstream either by sending an email to miros-mksh on the mirbsd.org domain (no subscription required to submit there) or (optionally) at Launchpad.

OpenSSL

All changes to the OpenSSL project at external/openssl should be made upstream at openssl.org.

V8

All changes to the V8 project at external/v8 should be submitted upstream at code.google.com/p/v8. See Contributing to V8 for details.

WebKit

All changes to the WebKit project at external/webkit should be made upstream at webkit.org. The process begins by filing a WebKit bug. This bug should use Android for the Platform and OS fields only if the bug is specific to Android. Bugs are far more likely to receive the reviewers' attention once a proposed fix is added and tests are included. See Contributing Code to WebKit for details.

zlib

All changes to the zlib project at external/zlib should be made upstream at zlib.net.