Submitting patches

This page describes the full process of submitting a patch to the Android Open Source Project (AOSP), including how to request a review and track your changes with Gerrit.

Prerequisites

To start, ensure you've done the following:

• Initialized your build environment
• Downloaded the source
• Created a password using the password generator.

Resources

• For details about Repo and Git, see the Source Control Tools page.
• For information about different roles within the Android Open Source community, see the Project roles page.
• For licensing information about contributing code to the Android platform, see the Licenses page.

Note: To make changes to upstream projects used by Android, you might need to make them directly to that project. See Upstream projects.

For contributors

Authenticating with the server

If you share an IP address with other users, quotas can be triggered even for regular usage patterns. This can happen when, for example, many users sync new clients from the same IP address within a short time period. Authenticated access uses a separate quota for each user, regardless of IP address. To read about activating authenticated access, see Using authentication.

Starting a Repo branch

For each change that 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 isn't included either on Gerrit or in the final source tree.

Making your change

Modify the source files, and validate your changes.

Commit the changes to your local repository with these commands:

git add -A
git commit -s

Always provide a detailed change description with each commit. Follow the format and guidelines provided under Change descriptions. This is very important; the change description gets pushed to the public AOSP repository. Follow this guidance whether you're submitting patches, or committing changes for a new feature.

Change descriptions

• Line 1: Headline

  Provide a one-line summary (50 characters maximum)

  This format is used by Git and Gerrit for various displays. It’s the most important, most dense part of your commit message. Consider using prefixes to describe the area you changed, followed by a description of the change you made in this commit, such as this one that has ui as the prefix:

  ui: Removes deprecated widget

• Line 2: Blank

  Keep this line blank, always.

• Line 3: Body

  Write a longer description, starting on this line.

  This must hard-wrap at 72 characters maximum. Describe what issue the change solves, and how. Although this is optional when implementing new features, it's very helpful to others later if they refer to this change, especially for debugging.

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

A unique change ID and your name and email, which are provided during repo init, are automatically added to your commit message.

Here's an example commit message:

Line 1, Headline - a short description

Line 3, Body - Add the detailed description of your patch here. Use as many lines
as needed. You can write an overall description, then list specifics.

I6e3c64e7a:Added a new widget.
I60c539a8f:Fixed the spinning image.

To read a blog about good commit descriptions (with examples), see How to Write a Git Commit Message by Chris Beams.

Uploading to Gerrit

After you commit your change to your personal history, upload it to Gerrit with this command:

repo upload

If you started multiple branches in the same repository, you're prompted to select which ones to upload.

After a successful upload, Repo provides you with the URL of a new page on Gerrit. Click the link that Repo gives you to view your patch on the review server, add comments, or request specific reviewers for your patch.

Requesting a review

After you've uploaded your changes to Gerrit, the patch must be reviewed and approved by the appropriate code owners. Locate code owners in OWNERS files.

To find the appropriate code owners and add them as reviewers for your change, follow these steps.

1. Select the SUGGEST OWNERS link in the Gerrit UI to see a list of code owners for the files in your patch.

   

   Figure 1. Suggest owners link in Gerrit

2. Add code owners from the list as reviewers for your patch.

To determine the status of the files in your patch, check for the following icons next to the files in the patch.

• (checkmark icon): Approved by code owner
• (cross icon): Not approved by code owner
• (clock icon): Pending approval by code owner

Figure 2. Example of files with icons showing code owner approval status

Uploading a replacement patch

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

Note: If you made other commits since uploading this patch, you must manually move your Git HEAD.

git add -A
git commit --amend

When you upload the amended patch, it replaces the original both on Gerrit and in your local Git history.

Resolving sync conflicts

If other patches are submitted to the source tree that conflict with yours, rebase your patch on top of the new HEAD of the source repository. To do so, run this command:

repo sync

The repo sync command 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, perform a manual rebase.

repo rebase

Another tool for dealing with the rebase conflict is git mergetool. When you've successfully merged the conflicting files, run this command:

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 can run repo sync to pull the update into their respective local clients.

For upstream projects

Android makes use of a number of other open source projects, such as the Linux kernel and WebKit, as described in Android Software Management. For most projects that reside under external/, make the changes upstream, then inform the Android maintainers of the new upstream release that contains your changes.

You might also upload patches that cause a new upstream release to be tracked. Note that these can be difficult changes to make if the project is widely used within Android, like most of the larger ones mentioned below, which are usually upgraded 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, please make an upstream fix, then a pull of a whole new file from the appropriate BSD.

Android Kernel

Make all changes upstream. For general guidance, follow the Android Kernel Contribution Guidelines and the Develop Kernel Code for GKI page.

ICU

Make all changes to the ICU project at external/icu (icu4c/ and icu4j/ folders) on the ICU-TC Home Page. See Submitting ICU Bugs and Feature Requests for more. Add the label “android” to all upstream Jira requests.

CLDR

Most linguistic data in ICU comes from the Unicode CLDR project. Submit all requests upstream according to Contributing to CLDR and add the label “android.”

LLVM/Clang/Compiler-rt

Make all changes to LLVM-related projects (external/clang, external/compiler-rt, external/llvm) on the LLVM Compiler Infrastructure page.

mksh

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

OpenSSL

Make all changes to the OpenSSL project at external/openssl on the OpenSSL page.

V8

Submit all changes to the V8 project at external/v8 on the V8 issue page. See Contributing to V8 for details.

WebKit

Make all changes to the WebKit project at external/webkit on the WebKit page. Start the process by filing a WebKit bug. In the bug, 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 after a proposed fix is added and tests are included. See Contributing Code to WebKit for details.

zlib

Make all changes to the zlib project at external/zlib on the zlib home page.