docs/source/submit-patches.jd

page.title=Android Contributors' Workflow
doc.type=source
@jd:body
<div>
<br>This page describes how to record changes to the Android files on your local client, upload those changes to the code-review server, and use Gerrit to track changes.<br><h2>
Prerequisites</h2>
Before you follow the instructions on this page, you will need to set up your
local working environment and get the Android source files. For instructions,
see <a href="{@docRoot}source/download.html">Get source</a>
.<br><br>Other recommended reading:<br><ul><li>For an overview of the code
contribution and review process, see <a
href="{@docRoot}source/life-of-a-patch.html">Life of a Patch</a>.</li>
<li>For details about Repo, see <a href="{@docRoot}source/git-repo.html">Using Repo and Git</a>.<br></li>
<li>For information about the different roles you can play within the Android
Open Source community, see <a href="{@docRoot}source/roles.html">Project roles</a>.</li>
<li>If you plan to contribute code to the Android platform, be sure to read
the <a href="{@docRoot}source/licenses.html">AOSP's licensing information</a>.</li>
<li>Note that changes to some of the upstream projects used by Android should be
made directly to that project, as described in
<a href="#upstream-projects">Upstream Projects</a>.
</ul>
<h2>
Working with the code</h2>
First, download the source into your working directory, as described in <a
href="{@docRoot}source/download.html">Get source</a>
. For information about how to choose which branch to use, see <a
href="{@docRoot}source/code-lines.html">Android Code-Lines</a>.<br><br>To work on a particular change to the code, follow these steps:<br>
<div><img src="{@docRoot}images/submit-patches-0.png">
</div>
<ol><li>Use repo start <i>branchname</i>
to start a new topic branch.</li>
<li>Edit the files.<br></li>
<li><span>Use git add to stage changes.</span>
<span>(Sometimes optional.)</span>
<br></li>
<li>Use repo status and git diff to view the status of your files.<i><br></i>
</li>
<li>Use git commit to commit changes.<br></li>
<li><span>Use repo upload to upload changes to the review server</span>
.<br></li>
</ol>
You can track your uploaded changes using the Gerrit code-review tool. When it's time to work on the code again, run repo sync, then go back to step 1 above and start another topic branch.<br><br>The steps will not always come in the order shown--for example, you might run git diff at several points in the process.<br><br><h3>
Starting a topic branch</h3>
Start a topic branch called default in your local work environment:<br><br>$ repo start default <br><br>For more about topic branches, see <a href="{@docRoot}source/git-repo.html">Using Repo and Git</a>.<br><h3>
Editing the files</h3>
You do not need to check files out before working on them. Edit the files using vim, emacs, or any other editor.<br><br><h3>
Staging changes</h3>
To indicate that every new and modified file in your working directory should be "staged" for inclusion in the next commit, run git add without any arguments. You can also specify files or filetypes. For example, the following command would stage all the new and modified files under the bionic directory and its subdirectories:<br><br>$ git add bionic/*<br><br>Run git help add to see more ways to use git add.<br><br><b>When is git add optional?<br></b>
<br>If you add new files, you must stage them using git add before you run git commit. However, if you are only modifying or deleting files, you can skip git add if you use the -a option with git commit. For more details, see the "Committing changes" section further down.<br><br><h3>
Using repo status <br></h3>
To see the status of the current branch, run <br><br>$ repo status .<br><br>For information about how to interpret the results of repo status, see <a href="{@docRoot}source/git-repo.html#TOC-status">Using Repo and Git</a>.<br><br><h3>
Using git diff</h3>
To see uncommitted changes, cd into the project directory and run <br><br>$ git
diff <br><br>Without any arguments, git diff will show you the differences
between the files in your working directory and the committed
files.<br><div><br><div><img src="{@docRoot}images/submit-patches-1.png">
</div>
<br></div>
<div>If you add the --cached option, git diff will show you the differences between the files in your working directory and the staged files.<br><br></div>
To see every edit that would go into the commit if you were to commit right now, make sure you are in the project directory and then run <br><br>$ git diff --cached <br><br><h3>
Committing changes</h3>
At intervals while you are working, commit your edits by using git commit from within the project directory:<br><span>$ cd ~/mydroid/<i>project-name</i>
</span>
<span><br>$ git commit</span>
<br><br>Every file that you staged using git add will be included in this commit.<br><br>If you have not added any new files that you want to commit, you can skip git add and simply run <br><br>$ git commit -a <br><br>The -a option will stage all the files you have modified or deleted and include them in this commit. (If you have added new files and want them included in the commit, you will need to use git add before you run git commit.)<br><br>If commit <span></span>
does not find changes to be committed, it will report "nothing to commit (working directory clean)". If commit finds changes to be committed, a file will open in which you can create a log message:<br><br><div><i>Your comments about this commit go here....</i>
<br># Please enter the commit message for your changes. Lines starting <br># with '#' will be ignored, and an empty message aborts the commit.<br># On branch master <br># Changes to be committed:<br>#(use "git reset HEADfile..." to unstage)<br>#<br>#new file:.repo/projects/gerrit-manifests.git/FETCH_HEAD <br>#new file:.repo/projects/gerrit-manifests.git/HEAD <br>#new file:.repo/projects/gerrit-manifests.git/config <br>.<br>.<br>.<br></div>
<br>If you do not add a log message, the commit will be aborted. Add a message and save the file.<br><br><h3>
Committing changes during code review</h3>
If you previously uploaded a change to Gerrit and the Approver has asked for changes, follow these steps:<br><ol><li>Edit the files to make the changes the Approver has requested.</li>
<li>Recommit your edits using the --amend flag, for example:<br><span>$ git commit -a --amend</span>
<br></li>
<li>See below to upload the changes to Gerrit again for another review cycle.</li>
</ol>
<h3>
Editing uploaded changes</h3>
To update an existing change with a new patch set:<br><ol><li>Make sure the updated branch is the currently checked out branch.</li>
<li>Use repo upload --replace <i>proj1</i>
to open the change matching editor.</li>
<li>For each commit in the series, enter the Gerrit change Id inside the brackets.</li>
</ol>
For more details, see <a href="{@docRoot}source/git-repo.html#TOC-upload">Using Repo and Git</a>
.<br><h3>
Uploading changes to Gerrit</h3>
To upload your committed changes to the review server:<br><ol><li>Complete the appropriate <a href="https://review.source.android.com/#settings,new-agreement">Contributor Agreement</a>
in Gerrit, granting the Android Open Source Project permission to distribute your changes to others.</li>
<li>Select an <a href="https://review.source.android.com/#settings,ssh-keys">SSH Username</a>
and upload your <a href="https://review.source.android.com/#settings,ssh-keys">public SSH key</a>
, so that Gerrit can identify you when you upload changes.Please note that due to a bug in repo, repo upload requires your SSH Username be the local part of your email address (the text on the left of the @ sign).<br><br>These first two steps are only necessary prior to your first change.Gerrit will remember your agreement and SSH key for subsequent changes.<br><br></li>
<li>Update to the latest revisions:<span><br></span>
<span>$</span>
<span>repo sync</span>
<br><br>For information about how to handle sync conflicts and how Repo synchronization works, see <a href="{@docRoot}source/git-repo.html#TOC-sync">Using Repo and Git</a>
.<br><br></li>
<li>Run repo upload to examine the list of all available changes and select which topic branches will be uploaded to the review server:<br><span>$</span>
<span>repo upload</span>
<br><br>This will open an editor window that will let you choose which topic branch to upload.If there is only one branch available, a simple y/n prompt is instead of an editor.<br></li>
</ol>
After a change is uploaded successfully:<br><ul><li>Repo will give you a URL where you can view your submission.</li>
<li>The code-review system will automatically notify the project owner about your submission.</li>
</ul>
For information about specifying particular projects with repo sync and repo upload, see <a href="{@docRoot}source/git-repo.html">Using Repo and Git</a>
.<br><br><h3>
Summary example <br></h3>
Here is a simple example that shows how you might work with the bionic/Android.mk file:<br><br>$ cd ~/mydroid/bionic <br>$ repo start default <br>$ vi Android.mk <br><i>...edit and save the file...</i>
<br>$ git commit -a <br>$ repo sync <br>$ repo upload <br><i>...close the editable window that opens...</i>
<br><i>...visit the provided URL to open Gerrit and track your change...</i>
<br><br><h3>
Downloading changes from Gerrit</h3>
To download a specific change from Gerrit, run <br><br>$ repo download <i>target change</i>
<br><br>where target is the local directory into which the change should be downloaded andchange is the change number as listed in <a href="https://review.source.android.com/">Gerrit</a>
. For more information, see <a href="{@docRoot}source/git-repo.html#TOC-download">Using Repo and Git</a>
.<br><br><h2>
Using the Gerrit code-review tool <br></h2>
You can open Gerrit by visiting whatever URL is returned to you from the repo upload command, or by visiting <a href="https://review.source.android.com/">https://review.source.android.com</a>.<br><br><h3>
Viewing the status of uploaded changes <br></h3>
To check the status of a change that you uploaded, open <a href="https://review.source.android.com/mine">Gerrit</a>
, sign in, and click MyChanges.<br><b><br></b>
<h3>
Reviewing a change <br></h3>
If you are assigned to be the Approver for a change, you need to determine the following:<br><ul><li>Does this change fit within this project's stated purpose?<br></li>
<li>Is this change valid within the project's existing architecture?</li>
<li>Does this change introduce design flaws that will cause problems in the future?</li>
<li>Does this change following the best practices that have been established for this project?</li>
<li>Is this change a good way to perform the described function?</li>
<li>Does this change introduce any security or instability risks?</li>
</ul>
If you approve of the change, you will then mark it with LGTM ("Looks Good to Me") within Gerrit.<br><br><h3>
Verifying a change <br></h3>
If you are assigned to be the Verifier for a change, you need to do the following:<br><ul><li>Patch the change into your local client using one of the Download commands.</li>
<li>Build and test the change.</li>
<li>Within Gerrit use Publish Comments to mark the commit as "Verified", or "Fails" (and add a message explaining what problems were identified).<br></li>
</ul>
<h3>
Viewing diffs and comments</h3>
To open the details of the change within Gerrit, click on the "Id number" or "Subject" of a change. To compare the established code with the updated code, click the file name under "Side-by-side diffs."<br>
<h3>
Adding comments</h3>
Anyone in the community can use Gerrit to add inline comments to code submissions. A good comment will be relevant to the line or section of code to which it is attached in Gerrit. It might be a short and constructive suggestion about how a line of code could be improved, or it might be an explanation from the author about why the code makes sense the way it is.<br><br>To add an inline comment, double-click the relevant line of the code and write your comment in the text box that opens. When you click Save, only you can see your comment.<br><br>To publish your comments so that others using Gerrit will be able to see them, click the Publish Comments button. Your comments will be emailed to all relevant parties for this change, including the change owner, the patch set uploader (if different from the owner), and all current reviewers.<br><br><h3>
After a submission is approved</h3>
After a submission makes it through the review and verification process, Gerrit automatically merges the change into the public repository. The change will now be visible in gitweb, and others users will be able to run repo sync to pull the update into their local client.<br><br><h3>
How do I become a Verifier or Approver?</h3>
In short, contribute high-quality code to one or more of the Android projects.
For details about the different roles in the Android Open Source community and
who plays them, see <a href="{@docRoot}source/roles.html">Project roles</a>
.<br><br><h2>
Using GitWeb to track patch histories</h2>
To view snapshots of the files that are in the public Android repositories and view file histories, use the <a href="http://android.git.kernel.org/">Android instance of GitWeb</a>
.<br>
<h2><a name="upstream-projects"></a>Upstream Projects</h2>
Android makes use of a number of other open-source projects, such as the Linux
kernel and WebKit, as described in
<a href="{@docRoot}source/code-lines.html">Branches &amp Releases</a>. For the
upstream projects detailed below, changes should be made directly upstream. Such
changes will be incorporated into the Android tree as part of the usual process
of pulling these projects.
<h3>WebKit</h3>
All changes to the WebKit project at <code>external/webkit</code> should be made
upstream at <a href="http://www.webkit.org">http://www.webkit.org</a>. The
process begins by filing a WebKit bug. This bug should use <code>Android</code>
for the <code>Platform</code> and <code>OS</code> 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
<a href="http://webkit.org/coding/contributing.html">Contributing Code to
WebKit</a> for details.
<h3>V8</h3>
All changes to the V8 project at <code>external/v8</code> should be submitted
upstream at
<a href="http://code.google.com/p/v8">http://code.google.com/p/v8</a>. See
<a href="http://code.google.com/p/v8/wiki/Contributing">Contributing to V8</a>
for details.
</div>