Submit code changes

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

AOSP relies on a Gerrit, a web-based code review system for projects that use Git.

Sign the contributor license agreements

Before you contribute any code changes for AOSP, you must read Contributor license agreements and headers and sign one of the following agreements:

• As an individual contributor making contributions only on your behalf, sign the Individual Contributor License Agreement.
• As an employee working for a corporation, ensure your company has signed the Corporate Contributor License Agreement authorizing you to make contributions on its behalf.

Note: To make changes to upstream projects used by Android, you need to make them directly to that project. For further information, see Contribute to upstream projects.

Start a branch

For each code change that you intend to make, perform the following steps:

1. Start a new branch within the relevant Git repository. A branch isn't a copy of the original files; it's a pointer to a specific commit, which makes creating local branches and switching among them a lightweight operation. By using branches, you can identify changes from each other. Run this command to start a branch:

   repo start BRANCH_NAME
   

   You can start several independent branches at the same time in the same repository. The branch BRANCH_NAME is local to your workspace and isn't included either on Gerrit or in the final source tree. Branches are also specific to the project you are in, so if you need to change files in different projects as part of the same change, you'll need a branch in each project where you change files.

2. (optional) Verify that the branch was created:

   repo status .
   

   You should see your newly created branch. For example:

   project frameworks/native/                      branch mynewbranch
   

   Note: You can also use repo branches to obtain a list of all branches, with the current branch (if any) preceded by an asterisk (*).

Make and test your change

Follow these steps to make and test your change:

1. To ensure you're working with the most current codebase, perform a sync of the entire codebase:

   repo sync
   

   Note: To just sync the current project, add a period (.) to the repo sync command: repo sync .. Syncing the current project is faster than syncing the entire repository.

   If you have any conflicts during the sync, refer to steps 2-4 of Resolve sync conflicts.

2. Find the code to change. To find code, consider using Android Code Search. You can use Android Code Search to view the AOSP source code as it's laid out when you actually use it. For more information, see Getting started with Code Search. To view all of the code in the main branch within Android code search, navigate to https://cs.android.com/android/platform/superproject/main.

3. Modify or add source files. For any changes made:

   • Follow the best practices in Include license headers.

   • For Java code, follow AOSP Java code style for contributors.

   • Some parts of AOSP are written in Kotlin (.kt) and you can use Kotlin in areas of the platform that are already written in Kotlin. For more information about Kotlin in Android, see the Android developer Kotlin style guide and Kotlin-Java interop guide. For more extensive Kotlin guidance, see the Kotlin language site.

   • When writing APIs, follow the Android API Guidelines. Use these guidelines to see the context behind Android's API decisions. Additions and modifications of platform APIs are validated by Metalava.

4. Build Android.

5. Test your build.

Stage and commit your change

A commit is the basic unit of revision control in Git and consists of a snapshot of the directory structure and file contents for the entire project. Follow these steps to commit your change:

1. By default, Git registers but doesn't track the changes that you make. To instruct Git to track your changes, you must mark or stage those changes for inclusion in a commit. Run this command to stage the change:

   git add -A
   

   This command tracks changes that you've made to any files.

   Note: If you just want to track changes to a specific file, use git add filename.
   Note: In addition to tracking changes to files, git add can be used to perform other operations, such as staging file modifications and deletions.

2. Take the files in the staging area and commit or store them in your local database:

   git commit -s
   

   By default, a text editor opens and you are prompted to provide a commit message.

3. Provide a commit message in the following format:

   • Line 1: Headline. Provide a one-line summary of the change (50 characters maximum). Consider using prefixes to describe the area you changed, followed by a description of the change you made in this commit, such as the following example containing a user interface change:

     ui: Removes deprecated widget
     

   • Line 2: Blank line. Follow the headline with a blank line.

   • Line 3: Body. Provide a long description that hard-wraps at 72 characters maximum. Describe what issue the change solves and how. Although the body is optional, it's helpful to others who need to refer back to the change. Be sure to include a brief note of any assumptions or background information that might be important when another contributor works on this feature.

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

4. Save the commit.

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

Upload the change for review

After you commit your change to your personal Git history, upload it to Gerrit:

1. Run the following command to upload all of your commits in all of your projects:

   repo upload
   

   All changes in all projects are included in the upload.

   Note: To upload changes only in the current project, add a period (.) to the repo upload command: repo upload ..
   Note: If you are working on a change that requires changes to files in multiple projects, use a topic in Gerrit to tie the changes together regardless of whether you use repo upload or repo upload .. The Gerrit topic ensures that the changes are kept together for the purposes of presubmit testing and through the automerger. For further information, see Using Topics

   You're prompted to run hook scripts.

2. Press a and then Enter.

   You're prompted to approve the upload:

   Upload project frameworks/native/ to remote branch main:
   branch BRANCH_NAME ( 1 commit, Wed Aug 7 09:32:33 2019 -0700):
          ff46b36d android codelab change
   to https://android-review.googlesource.com/ (y/N)?
   

   Note: If you started multiple branches in the same repository, you're prompted to select which ones to upload by uncommenting those branches in your text editor.

3. Press y and then Enter to approve the upload.

You should receive a message similar to remote: SUCCESS.

Request a review

After a successful upload, Repo provides you with a link to your changes in Gerrit. Click the link to view your changes on the review server, add comments, or request specific reviewers for your change. All changes to the code must be reviewed by the appropriate code owners. To request a review:

1. In Gerrit, click SUGGEST OWNERS:

   

   Figure 1. Suggest owners link in Gerrit.

   The reviewer dialog appears. This dialog contains a list of code owners who can review your change.

2. Click a code owner to add them to your review.

   Note: To understand how owners are determined, refer to the find-owners backend.

   The SEND button is activated.

3. (Optional) Type the email address of anyone else you'd like to review your change.

4. (Optional) Click +1 next to Autosubmit to automatically submit the change after you receive approvals. If you don't click this button, a Google employee has to submit your change for you.

5. Click SEND to send the change for review.

Code owners review your code changes and either provide feedback for you to resolve or approve the changes.

Determine status of change

To determine the status of the files in your change, check for the following icons next to the files in the change:

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

The following figure shows these status icons applied to files in a change:

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

Resolve feedback and upload a replacement change

If a reviewer requests a modification to your update, you can amend your commit within Git, which results in a new patchset on the same change.

Note: If you've created other branches and made other commits after uploading a change, you'll likely be working in the branch for one of those commits and not the branch for the original change. So, before you can resolve feedback for the original branch, you must navigate to that branch using the repo start EXISTING_BRANCH_NAME command.

To resolve feedback and amend your change:

1. Follow steps 2-4 in Make and test your change.

2. Run the following commands to amend your change:

   git add -A
   git commit --amend
   

3. Upload your change.

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

Resolve sync conflicts

If other changes are submitted to the source tree that conflict with yours, you receive a message that you have conflicts. To resolve the conflicts:

1. Ensure you're working with the most current code:

   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.

2. If the automatic rebase is unsuccessful, perform a manual rebase:

   repo rebase .
   

3. Resolve merge conflicts. If you don't have a preferred method for resolving merge conflicts, you can use git mergetool to manually fix conflicts between files.

4. When you've successfully fixed the conflicting files, run this command to apply the new commits:

   git rebase --continue
   

Submit change

After a submission makes it through the review and verification process, a Google reviewer must submit the code for you. Other users can run repo sync to pull the update into their respective local clients.

After your submission is merged, you can visit the Android Continuous Integration dashboard to monitor when your submissions are integrated into the tree.