Cleaning up source.android.com files.
This change fixes some formatting artifacts that resulted from the export from
Sites, and also updates links to no longer point to Sites and use the standard
{@docRoot} idiom. Also contains a few content updates, and introduces a page
about branch management.
diff --git a/pdk/docs/source/submit-patches.jd b/pdk/docs/source/submit-patches.jd
index afa6bf2..880a682 100644
--- a/pdk/docs/source/submit-patches.jd
+++ b/pdk/docs/source/submit-patches.jd
@@ -1,109 +1,32 @@
-page.title=Android Compatibility - Compatibility Test Suite
+page.title=Android Contributors' Workflow
doc.type=source
@jd:body
-<h3><span><b>Contribute</b>
-</span>
-</h3>
-<div><a href="http://source.android.com/download/using-repo">Using Repo and Git</a>
-<div><div><div><div><div><div><p><b>Contents</b>
-</p>
-<ol><li><a href="#TOC-Prerequisites"><b>1</b>
-Prerequisites</a>
-</li>
-<li><a href="#TOC-Working-with-the-code"><b>2</b>
-Working with the code</a>
-<ol><li><a href="#TOC-Starting-a-topic-branch"><b>2.1</b>
-Starting a topic branch</a>
-</li>
-<li><a href="#TOC-Editing-the-files"><b>2.2</b>
-Editing the files</a>
-</li>
-<li><a href="#TOC-Staging-changes"><b>2.3</b>
-Staging changes</a>
-</li>
-<li><a href="#TOC-Using-repo-status"><b>2.4</b>
-Using repo status</a>
-</li>
-<li><a href="#TOC-Using-git-diff"><b>2.5</b>
-Using git diff</a>
-</li>
-<li><a href="#TOC-Committing-changes"><b>2.6</b>
-Committing changes</a>
-</li>
-<li><a href="#TOC-Committing-changes-during-code-revi"><b>2.7</b>
-Committing changes during code review</a>
-</li>
-<li><a href="#TOC-Editing-uploaded-changes"><b>2.8</b>
-Editing uploaded changes</a>
-</li>
-<li><a href="#TOC-Uploading-changes-to-Gerrit"><b>2.9</b>
-Uploading changes to Gerrit</a>
-</li>
-<li><a href="#TOC-Summary-example"><b>2.10</b>
-Summary example</a>
-</li>
-<li><a href="#TOC-Downloading-changes-from-Gerrit"><b>2.11</b>
-Downloading changes from Gerrit</a>
-</li>
-</ol>
-</li>
-<li><a href="#TOC-Using-the-Gerrit-code-review-tool"><b>3</b>
-Using the Gerrit code-review tool</a>
-<ol><li><a href="#TOC-Viewing-the-status-of-uploaded-chan"><b>3.1</b>
-Viewing the status of uploaded changes</a>
-</li>
-<li><a href="#TOC-Reviewing-a-change"><b>3.2</b>
-Reviewing a change</a>
-</li>
-<li><a href="#TOC-Verifying-a-change"><b>3.3</b>
-Verifying a change</a>
-</li>
-<li><a href="#TOC-Viewing-diffs-and-comments"><b>3.4</b>
-Viewing diffs and comments</a>
-</li>
-<li><a href="#TOC-Adding-comments"><b>3.5</b>
-Adding comments</a>
-</li>
-<li><a href="#TOC-After-a-submission-is-approved"><b>3.6</b>
-After a submission is approved</a>
-</li>
-<li><a href="#TOC-How-do-I-become-a-Verifier-or-Appro"><b>3.7</b>
-How do I become a Verifier or Approver?</a>
-</li>
-</ol>
-</li>
-<li><a href="#TOC-Using-GitWeb-to-track-patch-histori"><b>4</b>
-Using GitWeb to track patch histories</a>
-</li>
-</ol>
-</div>
-</div>
-</div>
-</div>
-<table><tbody><tr><td>For information about current problems and fixes, see<a href="http://source.android.com/known-issues">Known issues</a>
-.</td>
-</tr>
-</tbody>
-</table>
<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="http://source.android.com/download">Get source</a>
-.<br><br>Other recommended reading:<br><ul><li>For an overview of the code contribution and review process, see<a href="http://source.android.com/submit-patches/workflow">Workflow</a>
+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/submit-patches.html">Workflow</a>
.</li>
-<li>For details about Repo, see<a href="http://source.android.com/download/using-repo">Using Repo and Git</a>
+<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="http://source.android.com/project">Project roles</a>
+<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 about<a href="http://source.android.com/license">contributor licenses</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>
</ul>
<h2>
Working with the code</h2>
-First, download the source into your working directory, as described in<a href="http://source.android.com/download">Get source</a>
-.<br><br>To work on a particular change to the code, follow these steps:<br>
+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>
+<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>
@@ -117,34 +40,32 @@
</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="http://source.android.com/download/using-repo">Using Repo and Git</a>
+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="http://source.android.com/download/using-repo#TOC-status">Using Repo and Git</a>
+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
+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>
-<div><a href="http://source.android.com/submit-patches/git-diff.gif?attredirects=0"><br></a>
-</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>
+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>
+<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># 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>
@@ -155,22 +76,22 @@
<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>
+<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="http://source.android.com/download/using-repo#TOC-upload">Using Repo and Git</a>
+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>
+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>
+<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="http://source.android.com/download/using-repo#TOC-sync">Using Repo and Git</a>
+<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>
@@ -179,28 +100,27 @@
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="http://source.android.com/download/using-repo">Using Repo and Git</a>
+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>
+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="http://source.android.com/download/using-repo#TOC-download">Using Repo and Git</a>
+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>
+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>
+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? (See<a href="http://source.android.com/projects">Project layout</a>
-.)<br></li>
+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>
@@ -208,7 +128,7 @@
<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>
+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>
@@ -222,10 +142,12 @@
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="http://source.android.com/project">Project roles</a>
+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>
+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></div>
</div>
</div>