Adding a slightly reorganized version of skyler's revamped s.a.c.
Change-Id: I19439883c25d887fa4409b33a70c235af3a78eaf
diff --git a/src/source/build-numbers.md b/src/source/build-numbers.md
new file mode 100644
index 0000000..b3e3836
--- /dev/null
+++ b/src/source/build-numbers.md
@@ -0,0 +1,70 @@
+# Codenames, Tags, and Build Numbers #
+
+At a high level, Android development happens around families of
+releases, which use code names ordered alphabetically after tasty
+treats.
+
+The code names match the following version numbers, along with
+API levels and NDK releases provided for convenience:
+
+Code name | Version | API level
+---------------|---------|------------
+(no code name) | 1.0 | API level 1
+(no code name) | 1.1 | API level 2
+Cupcake | 1.5 | API level 3, NDK 1
+Donut | 1.6 | API level 4, NDK 2
+Eclair | 2.0 | API level 5
+Eclair | 2.0.1 | API level 6
+Eclair | 2.1 | API level 7, NDK 3
+Froyo | 2.2.x | API level 8, NDK 4
+Gingerbread | 2.3.x | API level 9, NDK 5
+
+Starting with Cupcake, individual builds are identified with a short
+build code, e.g. FRF85B. The first letter is the code name of the
+release family, e.g. F is Froyo. The second letter is a branch code
+that allows Google to identify the exact code branch that the build
+was made from, and R is by convention the primary release branch.
+The next letter and two digits are a date code. The letter counts
+quarters, with A being Q1 2009. Therefore, F is Q2 2010. The two
+digits count days within the quarter, so F85 is June 24 2010.
+Finally, the last letter identifies individual versions related to
+the same date code, sequentially starting with A; A is actually
+implicit and usually omitted for brevity. The date code is not
+guaranteed to be the exact date at which a build was made, and it is
+common that minor variations added to an existing build re-use the
+same date code as that existing build.
+
+Starting with Donut, the exact list of tags and builds is in the
+following table:
+
+Build | Tag | Notes
+-------|--------------------|-----------------------------------
+DRC83 | android-1.6_r1.1 earliest Donut version, ADP1, ADP2
+DRC92 | android-1.6_r1.2
+DRD08 | android-1.6_r1.3
+DRD20 | android-1.6_r1.4
+DMD64 | android-1.6_r1.5 | latest Donut version
+ESD20 | android-2.0_r1 | earliest Eclair version
+ESD56 | android-2.0.1_r1
+ERD79 | android-2.1_r1 | Nexus One
+ERE27 | android-2.1_r2 | Nexus One
+EPE54B | android-2.1_r2.1p | Nexus One
+ESE81 | android-2.1_r2.1s
+EPF21B | android-2.1_r2.1p2 | latest Eclair version
+FRF85B | android-2.2_r1 | earliest Froyo version, Nexus One
+FRF91 | android-2.2_r1.1 | Nexus One
+FRG01B | android-2.2_r1.2
+FRG22D | android-2.2_r1.3
+FRG83 | android-2.2.1_r1 | Nexus One
+FRG83D | android-2.2.1_r2 | Nexus One
+FRG83G | android-2.2.2_r1 | latest Froyo version, Nexus One
+GRH55 | android-2.3_r1 | earliest Gingerbread version, Nexus S
+GRH78 | android-2.3.1_r1 | Nexus S
+GRH78C | android-2.3.2_r1 | latest Gingerbread version, Nexus S
+
+The branches donut, eclair, froyo, gingerbread represent development
+branches that do not exactly match configurations that were tested
+by Google. They might contain a variety of changes in addition to
+the official tagged releases, and those haven't been as thoroughly
+tested.
+
diff --git a/src/source/building-dream.md b/src/source/building-dream.md
new file mode 100644
index 0000000..9ba1187
--- /dev/null
+++ b/src/source/building-dream.md
@@ -0,0 +1,32 @@
+# Building for an Android Dev Phone #
+
+*The information on this page is a bit out of date. We'll update this
+page as soon as we can.*
+
+The basic manifest for 1.6 defines which projects are
+needed to do a generic build for the emulator or for unlocked Dream devices
+(e.g. the Android Dev Phone 1). You need to have an appropriate device running
+a matching official image.
+
+To build donut for dream (your
+device needs to be an ADP1 running an official 1.6 system):
+
+1. Follow the [normal steps](downloading.html) to setup repo and check out the sources.
+
+2. At the root of your source tree, run `. build/envsetup.sh` like you normally would for an emulator build.
+
+3. Run `make adb` if you don't already have adb in your path.
+
+4. run `adb root`.
+
+5. in `vendor/htc/dream-open/` there is a script called "extract-files.sh" that must be run (from that directory) to extract some proprietary binaries from your device (*). You only need to do this once.
+
+6. run `lunch aosp_dream_us-eng` to specifically configure the build system for dream (the default is the equivalent of "lunch generic-eng", which doesn't contain dream-specific files).
+
+7. run make from the top of the source tree.
+
+8. from this point, the fastboot tool (which is put automatically in your path) can be used to flash a device: boot the device into the bootloader by holding the back key while pressing the power key, and run `fastboot -w flashall`.
+
+Note: these instructions work for the sapphire (ADP2) build target, as
+well. Simply replace "dream" with "sapphire" above.
+
diff --git a/src/source/building.md b/src/source/building.md
new file mode 100644
index 0000000..20e34fa
--- /dev/null
+++ b/src/source/building.md
@@ -0,0 +1,147 @@
+# Building the System #
+
+The basic sequence of build commands is as follows:
+
+## Initialize ##
+
+Initialize the environment with the `envsetup.sh` script. Note
+that replacing "source" with a single dot saves a few characters,
+and the short form is more commonly used in documentation.
+
+ $ source build/envsetup.sh
+
+or
+
+ $ . build/envsetup.sh
+
+## Choose a Target ##
+
+Choose which target to build with `lunch`. The exact configuration can be passed as
+an argument, e.g.
+
+ $ lunch full-eng
+
+Common targets include
+
+- **full-eng**: emulator build with all debugging enabled
+- **full_passion-userdebug**: passion (Nexus One) build with minimal debugging
+- **full_crespo-userdebug**: crespo (Nexus S) build with minimal debugging.
+
+If run with no arguments `lunch` will prompt you to choose a target from the menu.
+
+All build targets take the form DEVICE-BUILDTYPE, where the DEVICE is a codename
+referring to the particular hardware:
+
+Codename | Device
+-----------|-----------
+passion | Nexus One
+crespo | Nexus S
+voles | Droid
+opal | myTouch/Sapphire
+
+and the BUILDTYPE is one of the following:
+
+Buildtype | Use
+------------|--------------------------------------
+user | limited access; suited for production
+userdebug | like "user" but with `su` access; preferred for debugging
+eng | unrestricted access
+
+## Build the Code ##
+
+Build everything with `make`. GNU make can handle parallel
+tasks with a `-jN` argument, and it's common to use a number of
+tasks N that's between 1 and 2 times the number of hardware
+threads on the computer being used for the build. E.g. on a
+dual-E5520 machine (2 CPUs, 4 cores per CPU, 2 threads per core),
+the fastest builds are made with commands between `make -j16` and
+`make -j32`.
+
+ $ make -j4
+
+## Run It! ##
+
+You can either run your build on an emulator or flash it on a device. Please note that you have already selected your build target with `lunch`, and it is unlikely at best to run on a different target than it was built for.
+
+### Flash a Device ###
+
+To flash a device, you will need to use `fastboot`, which should be included in your path after a successful build. Place the device in fastboot mode either manually by holding the appropriate key combination at boot, or from the shell with
+
+ $ adb reboot bootloader
+
+Once the device is in fastboot mode, run
+
+ $ fastboot flashall -w
+
+The `-w` option wipes the `/data` partition on the device; this is useful for your first time flashing a particular device, but is otherwise unnecessary.
+
+### Emulate an Android Device ###
+
+The emulator is added to your path automatically by the build process. To run the emulator, type
+
+ $ emulator
+
+
+# Troubleshooting Common Build Errors #
+
+## Wrong Java Version ##
+
+If you are attempting to build froyo or earlier with Java 1.6, or gingerbread or later
+with Java 1.5, `make` will abort with a message such as
+
+ ************************************************************
+ You are attempting to build with the incorrect version
+ of java.
+
+ Your version is: WRONG_VERSION.
+ The correct version is: RIGHT_VERSION.
+
+ Please follow the machine setup instructions at
+ http://source.android.com/download
+ ************************************************************
+
+This may be caused by
+
+- failing to install the correct JDK as specified on the [Initializing](initializing.html) page. Building Android requires Sun JDK 5 or 6 depending on which release you are building.
+
+- another JDK that you previously installed appearing in your path. You can remove the offending JDK from your path with:
+
+ $ export PATH=${PATH/\/path\/to\/jdk\/dir:/}
+
+## Python Version 3 ##
+
+Repo is built on particular functionality from Python 2.x and is unfortunately incompatible with Python 3. In order to use repo, please install Python 2.x:
+
+ $ apt-get install python
+
+## Gmake Version 3.82 ##
+
+There is a bug in `make` version 3.82 on Mac OS that prevents building Android.
+
+TODO: what the error looks like with GNU make 3.82 on older builds that don't explicitly detect it.
+
+Follow the instructions on the [Initializing](initializing.html) page for reverting GNU make from 3.82 to 3.81.
+
+## Case Insensitive Filesystem ##
+
+If you are building on an HFS filesystem on Mac OS X, you may encounter an error such as
+
+ ************************************************************
+ You are building on a case-insensitive filesystem.
+ Please move your source tree to a case-sensitive filesystem.
+ ************************************************************
+
+Please follow the instructions on the [Initializing](initializing.html) page for creating a case-sensitive disk image.
+
+## No USB Permission ##
+
+On most Linux systems, unprivileged users cannot access USB ports by default.
+
+TODO: what error will occur?
+
+Follow the instructions on the [Initializing](initializing.html) page for configuring USB access.
+
+If adb was already running and cannot connect to the device after
+getting those rules set up, it can be killed with `adb kill-server`.
+That will cause adb to restart with the new configuration.
+
diff --git a/src/source/cla-corporate.md b/src/source/cla-corporate.md
new file mode 100644
index 0000000..041aaf7
--- /dev/null
+++ b/src/source/cla-corporate.md
@@ -0,0 +1,58 @@
+# Corporate Contributor License Agreement #
+
+In order to clarify the intellectual property license granted with Contributions from any person or entity, the Android Open Source Project (the "Project") must have a Contributor License Grant ("Grant") on file that has been signed by each Contributor, indicating agreement to the license terms below. This license is for your protection as a Contributor as well as the protection of the Project and the Android Open Source Project Leads (the "Project Leads"); it does not change your rights to use your own Contributions for any other purpose.
+
+This version of the Grant allows an entity (the "Corporation") to submit Contributions to the Project Leads, to authorize Contributions submitted by its designated employees to the Project Leads, and to grant copyright and patent licenses thereto. If you have not already done so, please complete and send an original signed Grant to
+
+<blockquote>
+ Google Inc.<br/>
+ Attn: Open Source Program Office<br/>
+ 1600 Amphitheatre Pkwy<br/>
+ Building 43<br/>
+ Mountain View, CA 94043<br/>
+ U.S.A.
+</blockquote>
+
+Scanned agreements may also be emailed in PDF form to cla-submissions@google.com.
+
+If necessary, you may send it by facsimile to (650) 887-1625. Please read this document carefully before signing and keep a copy for your records.
+
+<pre>Corporation name: ___________________________________________________<br><br><br><br>Corporation address: ________________________________________________<br><br><br><br>_____________________________________________________________________<br><br><br><br>_____________________________________________________________________<br><br><br><br>Point of Contact: ___________________________________________________<br><br><br><br>E-Mail: ____________________________________________________________<br><br><br><br>Telephone: _____________________<br><br><br><br>Fax: ___________________________<br><br></pre>
+
+You accept and agree to the following terms and conditions for Your present and future Contributions submitted to the Project. Except for the license granted herein to the Project Leads and recipients of software distributed by the Project Leads, You reserve all right, title, and interest in and to Your Contributions.
+
+1. Definitions.
+
+ "You" (or "Your") shall mean the copyright owner or legal entity authorized by the copyright owner that is making this Grant to the Project Leads. For legal entities, the entity making a Contribution and all other entities that control, are controlled by, or are under common control with that entity are considered to be a single Contributor. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.
+
+ "Contribution" shall mean the code, documentation or other original works of authorship expressly identified in Schedule B, as well as any original work of authorship, including any modifications or additions to an existing work, that is intentionally submitted by You to the Project Leads for inclusion in, or documentation of, any of the products managed or maintained by the Project Leads (the "Work"). For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Project Leads or their representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Project Leads for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by You as "Not a Contribution."
+
+1. Grant of Copyright License. Subject to the terms and conditions of this Grant, You hereby grant to the Project Leads and to recipients of software distributed by the Project Leads a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare derivative works of, publicly display, publicly perform, sublicense, and distribute Your Contributions and such derivative works.
+
+1. Grant of Patent License. Subject to the terms and conditions of this Grant, You hereby grant to the Project Leads and to recipients of software distributed by the Project Leads a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by You that are necessarily infringed by Your Contribution(s) alone or by combination of Your Contribution(s) with the Work to which such Contribution(s) was submitted. If any entity institutes patent litigation against You or any other entity (including a cross-claim or counterclaim in a lawsuit) alleging that your Contribution, or the Work to which you have contributed, constitutes direct or contributory patent infringement, then any patent licenses granted to that entity under this Grant for that Contribution or Work shall terminate as of the date such litigation is filed.
+
+1. You represent that You are legally entitled to grant the above license. You represent further that each employee of the Corporation designated on Schedule A below (or in a subsequent written modification to that Schedule) is authorized to submit Contributions on behalf of the Corporation.
+
+1. You represent that each of Your Contributions is Your original creation (see section 7 for submissions on behalf of others).
+
+1. You are not expected to provide support for Your Contributions, except to the extent You desire to provide support. You may provide support for free, for a fee, or not at all. Unless required by applicable law or agreed to in writing, You provide Your Contributions on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE.
+
+1. Should You wish to submit work that is not Your original creation, You may submit it to the Project Leads separately from any Contribution, identifying the complete details of its source and of any license or other restriction (including, but not limited to, related patents, trademarks, and license agreements) of which you are personally aware, and conspicuously marking the work as "Submitted on behalf of a third-party: [named here]".<br></p>
+
+1. It is your responsibility to notify the Project Leads when any change is required to the list of designated employees authorized to submit Contributions on behalf of the Corporation, or to the Corporation's Point of Contact with the Project.
+
+<pre>
+<br><br>
+Please sign: __________________________________ Date: _______________<br><br>
+Title: _______________________________________________________________<br><br>
+Corporation: __________________________________________________________
+</pre>
+
+### Schedule A ###
+
+[Initial list of designated employees. NB: authorization is not tied to particular Contributions.]
+
+### Schedule B ###
+
+[Identification of optional concurrent software grant. Would be left blank or omitted if there is no concurrent software grant.]
+
diff --git a/src/source/cla-individual.md b/src/source/cla-individual.md
new file mode 100644
index 0000000..9957ab2
--- /dev/null
+++ b/src/source/cla-individual.md
@@ -0,0 +1,48 @@
+# Contributor License Agreement for Individuals #
+
+*Please visit the [code review tool](https://review.source.android.com/#settings,new-agreement)
+to execute the grant online.This page provides the text of the Individual Contributor License Grant for your quick review.*
+
+In order to clarify the intellectual property license granted with Contributions from any person or entity, the Android Open Source Project (the "Project") must have a Contributor License Grant ("Grant") on file that has been signed by each Contributor, indicating agreement to the license terms below. This license is for your protection as a Contributor as well as the protection of the Project and the Android Open Source Project Leads (the "Project Leads"); it does not change your rights to use your own Contributions for any other purpose. If you have not already done so, please complete and send an original signed Grant to
+
+<blockquote>
+ Google Inc.<br/>
+ Attn: Open Source Program Office<br/>
+ 1600 Amphitheatre Pkwy<br/>
+ Building 43<br/>
+ Mountain View, CA 94043<br/>
+ U.S.A.
+</blockquote>
+
+Scanned agreements may also be emailed in PDF form to cla-submissions@google.com, sent by facsimile to (650) 887-1625, or [signed electronically](https://review.source.android.com/#settings,new-agreement).
+
+Please read this document carefully before signing and keep a copy for your records.
+
+<pre>
+<br><br>
+Full name: ____________________________ E-Mail: ______________________<br><br>
+Mailing Address: ______________________ Telephone: ___________________<br><br>
+_______________________________________ Facsimile: ___________________<br><br>
+_______________________________________ Country: ___________________
+</pre>
+
+You accept and agree to the following terms and conditions for Your present and future Contributions submitted to the Project. Except for the license granted herein to the Project Leads and recipients of software distributed by the Project Leads, You reserve all right, title, and interest in and to Your Contributions.
+
+1. Definitions.
+
+ "You" (or "Your") shall mean the copyright owner or legal entity authorized by the copyright owner that is making this Grant. For legal entities, the entity making a Contribution and all other entities that control, are controlled by, or are under common control with that entity are considered to be a single Contributor. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity. "Contribution" shall mean any original work of authorship, including any modifications or additions to an existing work, that is intentionally submitted by You to the Project Leads for inclusion in, or documentation of, any of the products managed or maintained by the Project Leads (the "Work"). For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Project Leads or their representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Project Leads for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by You as "Not a Contribution."
+
+1. Grant of Copyright License. Subject to the terms and conditions of this Grant, You hereby grant to the Project Leads and to recipients of software distributed by the Project Leads a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare derivative works of, publicly display, publicly perform, sublicense, and distribute Your Contributions and such derivative works.
+
+1. Grant of Patent License. Subject to the terms and conditions of this Grant, You hereby grant to the Project Leads and to recipients of software distributed by the Project Leads a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by You that are necessarily infringed by Your Contribution(s) alone or by combination of Your Contribution(s) with the Work to which such Contribution(s) was submitted. If any entity institutes patent litigation against You or any other entity (including a cross-claim or counterclaim in a lawsuit) alleging that your Contribution, or the Work to which you have contributed, constitutes direct or contributory patent infringement, then any patent licenses granted to that entity under this Grant for that Contribution or Work shall terminate as of the date such litigation is filed.
+
+1. You represent that you are legally entitled to grant the above license. If your employer(s) has rights to intellectual property that you create that includes your Contributions, you represent that you have received permission to make Contributions on behalf of that employer, that your employer has waived such rights for your Contributions to the Project Leads, or that your employer has executed a separate Corporate Contributor License Grant with the Project Leads.
+
+1. You represent that each of Your Contributions is Your original creation (see section 7 for submissions on behalf of others). You represent that Your Contribution submissions include complete details of any third-party license or other restriction (including, but not limited to, related patents and trademarks) of which you are personally aware and which are associated with any part of Your Contributions.
+
+1. You are not expected to provide support for Your Contributions, except to the extent You desire to provide support. You may provide support for free, for a fee, or not at all. Unless required by applicable law or agreed to in writing, You provide Your Contributions on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON- INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE.
+
+1. Should You wish to submit work that is not Your original creation, You may submit it to the Project Leads separately from any Contribution, identifying the complete details of its source and of any license or other restriction (including, but not limited to, related patents, trademarks, and license agreements) of which you are personally aware, and conspicuously marking the work as "Submitted on behalf of a third-party: [named here]".<br></p>
+
+1. You agree to notify the Project Leads of any facts or circumstances of which you become aware that would make these representations inaccurate in any respect.
+
diff --git a/src/source/code-lines.md b/src/source/code-lines.md
new file mode 100644
index 0000000..67b2c00
--- /dev/null
+++ b/src/source/code-lines.md
@@ -0,0 +1,97 @@
+# Android Code-Lines #
+
+The Android Open Source Project maintains a complete software stack intended
+to be ported by OEMs and other device implementors to run on actual hardware.
+Accordingly, we maintain a number of "code lines" to clearly separate the
+current stable version of Android from unstable experimental work.
+
+The chart below depicts at a conceptual level how AOSP manages code and
+releases. We're referring to these as "code lines" instead of "branches"
+simply because at any given moment there may be more than one branch extant
+for a given "code line". For instance, when a release is cut, sometimes that
+will become a new branch in git, and sometimes not, based on the needs of the
+moment.
+
+<img src="/images/code-lines.png"/>
+
+## Notes and Explanations ##
+
+- A *release* corresponds to a formal version of the Android platform, such
+as 1.5, 2.1, and so on. Generally speaking, a release of the platform
+corresponds to a version of the `SdkVersion` field used in
+AndroidManifest.xml files, and defined in `frameworks/base/api` in
+the source tree.
+
+- An *upstream* project is an open-source project from which the Android
+stack is pulling code. These include obvious projects such as the Linux kernel
+and WebKit, but over time we are migrating some of the semi-autonomous
+Android projects (such as Dalvik, the Android SDK tools, Bionic, and so on) to
+work as "upstream" projects. Generally, these projects are developed entirely in
+the public tree. For some upstream projects, development is done by contributing
+directly to the upstream project itself. See [Upstream Projects](submit-patches.html#upstream-projects)
+for details. In both cases, snapshots will be periodically pulled into releases.
+
+- The diagram refers to "Eclair" and "FroYo"; however, they are simply
+placeholders, and the diagram actually reflects the overall release and
+branching strategy.
+
+- At all times, a release code-line (which may actually consist of
+more than one actual branch in git) is considered the sole canonical source
+code for a given Android platform version. OEMs and other groups building devices
+should pull only from a release branch.
+
+- We will set up "experimental" code-lines to capture changes from
+the community, so that they can be iterated on, with an eye toward stability.
+
+- Changes that prove stable will eventually be pulled into a release
+branch. Note that this will only apply to bug fixes, app improvements, and
+other things that do not affect the APIs of the platform.
+
+- Changes will be pulled into release branches from upstream projects
+(including the Android "upstream" projects) as necessary.
+
+- The "n+1"th version (that is, next major version of the framework and
+platform APIs) will be developed by Google internally. See below for
+details.
+
+- Changes will be pulled from upstream, release, and experimental branches
+into Google's private branch as necessary.
+
+- When the platform APIs for the next version have stabilized and been fully
+tested, Google will cut a release of the next platform version. (This
+specifically refers to a new `SdkVersion`.) This will also
+correspond to the internal code-line being made a public release branch, and the
+new current platform code-line.
+
+- When a new platform version is cut, a corresponding experimental
+code-line will be created at the same time.
+
+## About Private Code-Lines ##
+
+The source management strategy above includes a code-line that Google will
+keep private. The reason for this is to focus attention on the current public
+version of Android.
+
+OEMs and other device builders naturally want to ship devices with the
+latest version of Android. Similarly, application developers don't want to
+deal with more extant platform versions than strictly necessary. Meanwhile,
+Google retains responsibility for the strategic direction of Android as a
+platform and a product. Our approach is based on focusing on a small number of
+flagship devices to drive features, and secure protections of Android-related
+intellectual property.
+
+As a result, Google frequently has possession of confidential
+information of third parties, and we must refrain from revealing sensitive
+features until we've secured the appropriate protections. Meanwhile, there are
+real risks to the platform arising from having too many platform versions
+extant at once. For these reasons, we have structured the open-source project
+-- including third-party contributions -- to focus on the currently-public
+stable version of Android. "Deep development" on the next version of the
+platform will happen in private, until it's ready to become an official
+release.
+
+We recognize that many contributors will disagree with this approach. We
+respect that others may have a different point of view; however, this is the
+approach that we feel is best, and the one we've chosen to implement.
+
+
diff --git a/src/source/code-style.md b/src/source/code-style.md
new file mode 100644
index 0000000..d3d09bc
--- /dev/null
+++ b/src/source/code-style.md
@@ -0,0 +1,733 @@
+# Code Style Guidelines for Contributors #
+
+The rules below are not guidelines or recommendations, but strict rules.
+Contributions to Android generally *will not be accepted* if they do not
+adhere to these rules.
+
+Not all existing code follows these rules, but all new code is expected to.
+
+[TOC]
+
+## Java Language Rules ##
+
+We follow standard Java coding conventions. We add a few rules:
+
+### Don't Ignore Exceptions ###
+
+Sometimes it is tempting to write code that completely ignores an exception
+like this:
+
+<!--div style="display: inline-block"> <!-- Just to make the code not overlap the ToC -->
+
+ void setServerPort(String value) {
+ try {
+ serverPort = Integer.parseInt(value);
+ } catch (NumberFormatException e) { }
+ }
+
+<!-- /div -->
+
+You must never do this. While you may think that your code will never
+encounter this error condition or that it is not important to handle it,
+ignoring exceptions like above creates mines in your code for someone else to
+trip over some day. You must handle every Exception in your code in some
+principled way. The specific handling varies depending on the case.
+
+*Anytime somebody has an empty catch clause they should have a
+creepy feeling. There are definitely times when it is actually the correct
+thing to do, but at least you have to think about it. In Java you can't escape
+the creepy feeling.* -[James Gosling](http://www.artima.com/intv/solid4.html)
+
+Acceptable alternatives (in order of preference) are:
+
+- Throw the exception up to the caller of your method.
+
+ void setServerPort(String value) throws NumberFormatException {
+ serverPort = Integer.parseInt(value);
+ }
+
+- Throw a new exception that's appropriate to your level of abstraction.
+
+ void setServerPort(String value) throws ConfigurationException {
+ try {
+ serverPort = Integer.parseInt(value);
+ } catch (NumberFormatException e) {
+ throw new ConfigurationException("Port " + value + " is not valid.");
+ }
+ }
+
+- Handle the error gracefully and substitute an appropriate value in the
+catch {} block.
+
+ /** Set port. If value is not a valid number, 80 is substituted. */
+
+ void setServerPort(String value) {
+ try {
+ serverPort = Integer.parseInt(value);
+ } catch (NumberFormatException e) {
+ serverPort = 80; // default port for server
+ }
+ }
+
+- Catch the Exception and throw a new `RuntimeException`. This is dangerous:
+only do it if you are positive that if this error occurs, the appropriate
+thing to do is crash.
+
+ /** Set port. If value is not a valid number, die. */
+
+ void setServerPort(String value) {
+ try {
+ serverPort = Integer.parseInt(value);
+ } catch (NumberFormatException e) {
+ throw new RuntimeException("port " + value " is invalid, ", e);
+ }
+ }
+
+ Note that the original exception is passed to the constructor for
+ RuntimeException. If your code must compile under Java 1.3, you will need to
+ omit the exception that is the cause.
+
+- Last resort: if you are confident that actually ignoring the exception is
+appropriate then you may ignore it, but you must also comment why with a good
+reason:
+
+ /** If value is not a valid number, original port number is used. */
+ void setServerPort(String value) {
+ try {
+ serverPort = Integer.parseInt(value);
+ } catch (NumberFormatException e) {
+ // Method is documented to just ignore invalid user input.
+ // serverPort will just be unchanged.
+ }
+ }
+
+### Don't Catch Generic Exception ###
+
+Sometimes it is tempting to be lazy when catching exceptions and do
+something like this:
+
+ try {
+ someComplicatedIOFunction(); // may throw IOException
+ someComplicatedParsingFunction(); // may throw ParsingException
+ someComplicatedSecurityFunction(); // may throw SecurityException
+ // phew, made it all the way
+ } catch (Exception e) { // I'll just catch all exceptions
+ handleError(); // with one generic handler!
+ }
+
+You should not do this. In almost all cases it is inappropriate to catch
+generic Exception or Throwable, preferably not Throwable, because it includes
+Error exceptions as well. It is very dangerous. It means that Exceptions you
+never expected (including RuntimeExceptions like ClassCastException) end up
+getting caught in application-level error handling. It obscures the failure
+handling properties of your code. It means if someone adds a new type of
+Exception in the code you're calling, the compiler won't help you realize you
+need to handle that error differently. And in most cases you shouldn't be
+handling different types of exception the same way, anyway.
+
+There are rare exceptions to this rule: certain test code and top-level
+code where you want to catch all kinds of errors (to prevent them from showing
+up in a UI, or to keep a batch job running). In that case you may catch
+generic Exception (or Throwable) and handle the error appropriately. You
+should think very carefully before doing this, though, and put in comments
+explaining why it is safe in this place.
+
+Alternatives to catching generic Exception:
+
+- Catch each exception separately as separate catch blocks after a single
+try. This can be awkward but is still preferable to catching all Exceptions.
+Beware repeating too much code in the catch blocks.</li>
+
+- Refactor your code to have more fine-grained error handling, with multiple
+try blocks. Split up the IO from the parsing, handle errors separately in each
+case.
+
+- Rethrow the exception. Many times you don't need to catch the exception at
+this level anyway, just let the method throw it.
+
+Remember: exceptions are your friend! When the compiler complains you're
+not catching an exception, don't scowl. Smile: the compiler just made it
+easier for you to catch runtime problems in your code.
+
+### Don't Use Finalizers ###
+
+Finalizers are a way to have a chunk of code executed
+when an object is garbage collected.
+
+Pros: can be handy for doing cleanup, particularly of external resources.
+
+Cons: there are no guarantees as to when a finalizer will be called,
+or even that it will be called at all.
+
+Decision: we don't use finalizers. In most cases, you can do what
+you need from a finalizer with good exception handling. If you absolutely need
+it, define a close() method (or the like) and document exactly when that
+method needs to be called. See InputStream for an example. In this case it is
+appropriate but not required to print a short log message from the finalizer,
+as long as it is not expected to flood the logs.
+
+### Fully Qualify Imports ###
+
+When you want to use class Bar from package foo,there
+are two possible ways to import it:
+
+1. `import foo.*;`
+
+Pros: Potentially reduces the number of import statements.
+
+1. `import foo.Bar;`
+
+Pros: Makes it obvious what classes are actually used. Makes
+code more readable for maintainers.
+
+Decision: Use the latter for importing all Android code. An explicit
+exception is made for java standard libraries (`java.util.*`, `java.io.*`, etc.)
+and unit test code (`junit.framework.*`)
+
+## Java Library Rules ##
+
+There are conventions for using Android's Java libraries and tools. In some
+cases, the convention has changed in important ways and older code might use a
+deprecated pattern or library. When working with such code, it's okay to
+continue the existing style (see [Consistency](#consistency)). When
+creating new components never use deprecated libraries.
+
+## Java Style Rules ##
+
+### Use Javadoc Standard Comments ###
+
+Every file should have a copyright statement at the top. Then a package
+statement and import statements should follow, each block separated by a blank
+line. And then there is the class or interface declaration. In the Javadoc
+comments, describe what the class or interface does.
+
+ /*
+ * Copyright (C) 2010 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+ package com.android.internal.foo;
+
+ import android.os.Blah;
+ import android.view.Yada;
+
+ import java.sql.ResultSet;
+ import java.sql.SQLException;
+
+ /**
+ * Does X and Y and provides an abstraction for Z.
+ */
+
+ public class Foo {
+ ...
+ }
+
+Every class and nontrivial public method you write *must* contain a
+Javadoc comment with at least one sentence describing what the class or method
+does. This sentence should start with a 3rd person descriptive verb.
+
+Examples:
+
+ /** Returns the correctly rounded positive square root of a double value. */
+ static double sqrt(double a) {
+ ...
+ }
+
+or
+
+ /**
+ * Constructs a new String by converting the specified array of
+ * bytes using the platform's default character encoding.
+ */
+ public String(byte[] bytes) {
+ ...
+ }
+
+You do not need to write Javadoc for trivial get and set methods such as
+`setFoo()` if all your Javadoc would say is "sets Foo". If the method does
+something more complex (such as enforcing a constraint or having an important
+side effect), then you must document it. And if it's not obvious what the
+property "Foo" means, you should document it.
+
+Every method you write, whether public or otherwise, would benefit from
+Javadoc. Public methods are part of an API and therefore require Javadoc.
+
+Android does not currently enforce a specific style for writing Javadoc
+comments, but you should follow the
+[Sun Javadoc conventions](http://java.sun.com/j2se/javadoc/writingdoccomments/).
+
+### Write Short Methods ###
+
+To the extent that it is feasible, methods should be kept small and
+focused. It is, however, recognized that long methods are sometimes
+appropriate, so no hard limit is placed on method length. If a method exceeds
+40 lines or so, think about whether it can be broken up without harming the
+structure of the program.
+
+### Define Fields in Standard Places ###
+
+Fields should be defined either at the top of the file, or immediately before the methods that use them.
+
+### Limit Variable Scope ###
+
+The scope of local variables should be kept to a minimum (*Effective
+Java* Item 29). By doing so, you increase the readability and
+maintainability of your code and reduce the likelihood of error. Each variable
+should be declared in the innermost block that encloses all uses of the
+variable.
+
+Local variables should be declared at the point they are first used. Nearly
+every local variable declaration should contain an initializer. If you don't
+yet have enough information to initialize a variable sensibly, you should
+postpone the declaration until you do.
+
+One exception to this rule concerns try-catch statements. If a variable is
+initialized with the return value of a method that throws a checked exception,
+it must be initialized inside a try block. If the value must be used outside
+of the try block, then it must be declared before the try block, where it
+cannot yet be sensibly initialized:
+
+ // Instantiate class cl, which represents some sort of Set
+ Set s = null;
+ try {
+ s = (Set) cl.newInstance();
+ } catch(IllegalAccessException e) {
+ throw new IllegalArgumentException(cl + " not accessible");
+ } catch(InstantiationException e) {
+ throw new IllegalArgumentException(cl + " not instantiable");
+ }
+
+ // Exercise the set
+ s.addAll(Arrays.asList(args));
+
+But even this case can be avoided by encapsulating the try-catch block in a method:
+
+ Set createSet(Class cl) {
+ // Instantiate class cl, which represents some sort of Set
+ try {
+ return (Set) cl.newInstance();
+ } catch(IllegalAccessException e) {
+ throw new IllegalArgumentException(cl + " not accessible");
+ } catch(InstantiationException e) {
+ throw new IllegalArgumentException(cl + " not instantiable");
+ }
+ }
+
+ ...
+
+ // Exercise the set
+ Set s = createSet(cl);
+ s.addAll(Arrays.asList(args));
+
+Loop variables should be declared in the for statement itself unless there
+is a compelling reason to do otherwise:
+
+ for (int i = 0; i n; i++) {
+ doSomething(i);
+ }
+
+and
+
+ for (Iterator i = c.iterator(); i.hasNext(); ) {
+ doSomethingElse(i.next());
+ }
+
+### Order Import Statements ###
+
+The ordering of import statements is:
+
+1. Android imports
+
+1. Imports from third parties (`com`, `junit`, `net`, `org`)
+
+1. `java` and `javax`
+
+To exactly match the IDE settings, the imports should be:
+
+- Alphabetical within each grouping, with capital letters before lower case letters (e.g. Z before a).
+
+- There should be a blank line between each major grouping (`android`, `com`, `junit`, `net`, `org`, `java`, `javax`).
+
+Originally there was no style requirement on the ordering. This meant that
+the IDE's were either always changing the ordering, or IDE developers had to
+disable the automatic import management features and maintain the imports by
+hand. This was deemed bad. When java-style was asked, the preferred styles
+were all over the map. It pretty much came down to our needing to "pick an
+ordering and be consistent." So we chose a style, updated the style guide, and
+made the IDEs obey it. We expect that as IDE users work on the code, the
+imports in all of the packages will end up matching this pattern without any
+extra engineering effort.
+
+This style was chosen such that:
+
+- The imports people want to look at first tend to be at the top (`android`)
+
+- The imports people want to look at least tend to be at the bottom (`java`)
+
+- Humans can easily follow the style
+
+- IDEs can follow the style
+
+The use and location of static imports have been mildly controversial
+issues. Some people would prefer static imports to be interspersed with the
+remaining imports, some would prefer them reside above or below all other
+imports. Additinally, we have not yet come up with a way to make all IDEs use
+the same ordering.
+
+Since most people consider this a low priority issue, just use your
+judgement and please be consistent.
+
+### Use Spaces for Indentation ###
+
+We use 4 space indents for blocks. We never use tabs. When in doubt, be
+consistent with code around you.
+
+We use 8 space indents for line wraps, including function calls and
+assignments. For example, this is correct:
+
+ Instrument i =
+ someLongExpression(that, wouldNotFit, on, one, line);
+
+and this is not correct:
+
+ Instrument i =
+ someLongExpression(that, wouldNotFit, on, one, line);
+
+### Follow Field Naming Conventions ###
+
+- Non-public, non-static field names start with m.
+
+- Static field names start with s.
+
+- Other fields start with a lower case letter.
+
+- Public static final fields (constants) are ALL_CAPS_WITH_UNDERSCORES.
+
+For example:
+
+ public class MyClass {
+ public static final int SOME_CONSTANT = 42;
+ public int publicField;
+ private static MyClass sSingleton;
+ int mPackagePrivate;
+ private int mPrivate;
+ protected int mProtected;
+ }
+
+### Use Standard Brace Style ###
+
+Braces do not go on their own line; they go on the same line as the code
+before them. So:
+
+ class MyClass {
+ int func() {
+ if (something) {
+ // ...
+ } else if (somethingElse) {
+ // ...
+ } else {
+ // ...
+ }
+ }
+ }
+
+We require braces around the statements for a conditional. Except, if the
+entire conditional (the condition and the body) fit on one line, you may (but
+are not obligated to) put it all on one line. That is, this is legal:
+
+ if (condition) {
+ body();
+ }
+
+and this is legal:
+
+ if (condition) body();
+
+but this is still illegal:
+
+ if (condition)
+ body(); // bad!
+
+### Limit Line Length ###
+
+Each line of text in your code should be at most 100 characters long.
+
+There has been lots of discussion about this rule and the decision remains
+that 100 characters is the maximum.
+
+Exception: if a comment line contains an example command or a literal URL
+longer than 100 characters, that line may be longer than 100 characters for
+ease of cut and paste.
+
+Exception: import lines can go over the limit because humans rarely see
+them. This also simplifies tool writing.
+
+### Use Standard Java Annotations ###
+
+Annotations should precede other modifiers for the same language element.
+Simple marker annotations (e.g. @Override) can be listed on the same line with
+the language element. If there are multiple annotations, or parameterized
+annotations, they should each be listed one-per-line in alphabetical
+order.<
+
+Android standard practices for the three predefined annotations in Java are:
+
+- `@Deprecated`: The @Deprecated annotation must be used whenever the use of the annotated
+element is discouraged. If you use the @Deprecated annotation, you must also
+have a @deprecated Javadoc tag and it should name an alternate implementation.
+In addition, remember that a @Deprecated method is *still supposed to
+work.*
+
+ If you see old code that has a @deprecated Javadoc tag, please add the @Deprecated annotation.
+
+- `@Override`: The @Override annotation must be used whenever a method overrides the
+declaration or implementation from a super-class.
+
+ For example, if you use the @inheritdocs Javadoc tag, and derive from a
+ class (not an interface), you must also annotate that the method @Overrides
+ the parent class's method.
+
+- `@SuppressWarnings`: The @SuppressWarnings annotation should only be used under circumstances
+where it is impossible to eliminate a warning. If a warning passes this
+"impossible to eliminate" test, the @SuppressWarnings annotation *must* be
+used, so as to ensure that all warnings reflect actual problems in the
+code.
+
+ When a @SuppressWarnings annotation is necessary, it must be prefixed with
+ a TODO comment that explains the "impossible to eliminate" condition. This
+ will normally identify an offending class that has an awkward interface. For
+ example:
+
+ // TODO: The third-party class com.third.useful.Utility.rotate() needs generics
+ @SuppressWarnings("generic-cast")
+ List<String> blix = Utility.rotate(blax);
+
+ When a @SuppressWarnings annotation is required, the code should be
+ refactored to isolate the software elements where the annotation applies.
+
+### Treat Acronyms as Words ###
+
+Treat acronyms and abbreviations as words in naming variables, methods, and classes. The names are much more readable:
+
+Good | Bad
+---------------|-------
+XmlHttpRequest | XMLHTTPRequest
+getCustomerId | getCustomerID
+class Html | class HTML
+String url | String URL
+long id | long ID
+
+Both the JDK and the Android code bases are very inconsistent with regards
+to acronyms, therefore, it is virtually impossible to be consistent with the
+code around you. Bite the bullet, and treat acronyms as words.
+
+For further justifications of this style rule, see *Effective Java*
+Item 38 and *Java Puzzlers* Number 68.
+
+### Use TODO Comments ###
+
+Use TODO comments for code that is temporary, a short-term solution, or
+good-enough but not perfect.
+
+TODOs should include the string TODO in all caps, followed by a colon:
+
+ // TODO: Remove this code after the UrlTable2 has been checked in.
+
+and
+
+ // TODO: Change this to use a flag instead of a constant.
+
+If your TODO is of the form "At a future date do something" make sure that
+you either include a very specific date ("Fix by November 2005") or a very
+specific event ("Remove this code after all production mixers understand
+protocol V7.").
+
+### Log Sparingly ###
+
+While logging is necessary it has a significantly negative impact on
+performance and quickly loses its usefulness if it's not kept reasonably
+terse. The logging facilities provides five different levels of logging. Below
+are the different levels and when and how they should be used.
+
+- `ERROR`:
+This level of logging should be used when something fatal has happened,
+i.e. something that will have user-visible consequences and won't be
+recoverable without explicitly deleting some data, uninstalling applications,
+wiping the data partitions or reflashing the entire phone (or worse). This
+level is always logged. Issues that justify some logging at the ERROR level
+are typically good candidates to be reported to a statistics-gathering
+server.
+
+- `WARNING`:
+This level of logging should used when something serious and unexpected
+happened, i.e. something that will have user-visible consequences but is
+likely to be recoverable without data loss by performing some explicit action,
+ranging from waiting or restarting an app all the way to re-downloading a new
+version of an application or rebooting the device. This level is always
+logged. Issues that justify some logging at the WARNING level might also be
+considered for reporting to a statistics-gathering server.
+
+- `INFORMATIVE:`
+This level of logging should used be to note that something interesting to
+most people happened, i.e. when a situation is detected that is likely to have
+widespread impact, though isn't necessarily an error. Such a condition should
+only be logged by a module that reasonably believes that it is the most
+authoritative in that domain (to avoid duplicate logging by non-authoritative
+components). This level is always logged.
+
+- `DEBUG`:
+This level of logging should be used to further note what is happening on the
+device that could be relevant to investigate and debug unexpected behaviors.
+You should log only what is needed to gather enough information about what is
+going on about your component. If your debug logs are dominating the log then
+you probably should be using verbose logging.
+
+ This level will be logged, even
+on release builds, and is required to be surrounded by an `if (LOCAL_LOG)` or `if
+(LOCAL_LOGD)` block, where `LOCAL_LOG[D]` is defined in your class or
+subcomponent, so that there can exist a possibility to disable all such
+logging. There must therefore be no active logic in an `if (LOCAL_LOG)` block.
+All the string building for the log also needs to be placed inside the `if
+(LOCAL_LOG)` block. The logging call should not be re-factored out into a
+method call if it is going to cause the string building to take place outside
+of the `if (LOCAL_LOG)` block.
+
+ There is some code that still says `if
+(localLOGV)`. This is considered acceptable as well, although the name is
+nonstandard.
+
+- `VERBOSE`:
+This level of logging should be used for everything else. This level will only
+be logged on debug builds and should be surrounded by an `if (LOCAL_LOGV)` block
+(or equivalent) so that it can be compiled out by default. Any string building
+will be stripped out of release builds and needs to appear inside the `if (LOCAL_LOGV)` block.
+
+*Notes:*
+
+- Within a given module, other than at the VERBOSE level, an
+error should only be reported once if possible: within a single chain of
+function calls within a module, only the innermost function should return the
+error, and callers in the same module should only add some logging if that
+significantly helps to isolate the issue.
+
+- In a chain of modules, other than at the VERBOSE level, when a
+lower-level module detects invalid data coming from a higher-level module, the
+lower-level module should only log this situation to the DEBUG log, and only
+if logging provides information that is not otherwise available to the caller.
+Specifically, there is no need to log situations where an exception is thrown
+(the exception should contain all the relevant information), or where the only
+information being logged is contained in an error code. This is especially
+important in the interaction between the framework and applications, and
+conditions caused by third-party applications that are properly handled by the
+framework should not trigger logging higher than the DEBUG level. The only
+situations that should trigger logging at the INFORMATIVE level or higher is
+when a module or application detects an error at its own level or coming from
+a lower level.
+
+- When a condition that would normally justify some logging is
+likely to occur many times, it can be a good idea to implement some
+rate-limiting mechanism to prevent overflowing the logs with many duplicate
+copies of the same (or very similar) information.
+
+- Losses of network connectivity are considered common and fully
+expected and should not be logged gratuitously. A loss of network connectivity
+that has consequences within an app should be logged at the DEBUG or VERBOSE
+level (depending on whether the consequences are serious enough and unexpected
+enough to be logged in a release build).
+
+- A full filesystem on a filesystem that is acceessible to or on
+behalf of third-party applications should not be logged at a level higher than
+INFORMATIVE.
+
+- Invalid data coming from any untrusted source (including any
+file on shared storage, or data coming through just about any network
+connections) is considered expected and should not trigger any logging at a
+level higher then DEBUG when it's detected to be invalid (and even then
+logging should be as limited as possible).
+
+- Keep in mind that the `+` operator, when used on Strings,
+implicitly creates a `StringBuilder` with the default buffer size (16
+characters) and potentially quite a few other temporary String objects, i.e.
+that explicitly creating StringBuilders isn't more expensive than relying on
+the default '+' operator (and can be a lot more efficient in fact). Also keep
+in mind that code that calls `Log.v()` is compiled and executed on release
+builds, including building the strings, even if the logs aren't being
+read.
+
+- Any logging that is meant to be read by other people and to be
+available in release builds should be terse without being cryptic, and should
+be reasonably understandable. This includes all logging up to the DEBUG
+level.
+
+- When possible, logging should be kept on a single line if it
+makes sense. Line lengths up to 80 or 100 characters are perfectly acceptable,
+while lengths longer than about 130 or 160 characters (including the length of
+the tag) should be avoided if possible.
+
+- Logging that reports successes should never be used at levels
+higher than VERBOSE.
+
+- Temporary logging that is used to diagnose an issue that's
+hard to reproduce should be kept at the DEBUG or VERBOSE level, and should be
+enclosed by if blocks that allow to disable it entirely at compile-time.
+
+- Be careful about security leaks through the log. Private
+information should be avoided. Information about protected content must
+definitely be avoided. This is especially important when writing framework
+code as it's not easy to know in advance what will and will not be private
+information or protected content.
+
+- `System.out.println()` (or `printf()` for native code) should
+never be used. System.out and System.err get redirected to /dev/null, so your
+print statements will have no visible effects. However, all the string
+building that happens for these calls still gets executed.
+
+- *The golden rule of logging is that your logs may not
+unnecessarily push other logs out of the buffer, just as others may not push
+out yours.*
+
+### Be Consistent ###
+
+Our parting thought: BE CONSISTENT. If you're editing code, take a few
+minutes to look at the code around you and determine its style. If they use
+spaces around their if clauses, you should too. If their comments have little
+boxes of stars around them, make your comments have little boxes of stars
+around them too.
+
+The point of having style guidelines is to have a common vocabulary of
+coding, so people can concentrate on what you're saying, rather than on how
+you're saying it. We present global style rules here so people know the
+vocabulary. But local style is also important. If code you add to a a file
+looks drastically different from the existing code around it, it throws
+readers out of their rhythm when they go to read it. Try to avoid this.</p>
+
+## Javatests Style Rules ##
+
+### Follow Test Method Naming Conventions ###
+
+When naming test methods, you can use an underscore to seperate what is
+being tested from the specific case being tested. This style makes it easier
+to see exactly what cases are being tested.
+
+For example:
+
+ testMethod_specificCase1 testMethod_specificCase2
+
+
+ void testIsDistinguishable_protanopia() {
+ ColorMatcher colorMatcher = new ColorMatcher(PROTANOPIA)
+ assertFalse(colorMatcher.isDistinguishable(Color.RED, Color.BLACK))
+ assertTrue(colorMatcher.isDistinguishable(Color.X, Color.Y))
+ }
+
diff --git a/src/source/downloading.md b/src/source/downloading.md
new file mode 100644
index 0000000..835b808
--- /dev/null
+++ b/src/source/downloading.md
@@ -0,0 +1,97 @@
+# Downloading the Source Tree #
+
+## Installing Repo ##
+
+Repo is a tool that makes it easier to work with Git in the context of Android. For more information about Repo, see <a href="{@docRoot}source/git-repo.html">Using Repo and Git</a>.</p>
+
+To install, initialize, and configure Repo, follow these steps:
+
+ - Make sure you have a bin/ directory in your home directory, and that it is included in your path:
+
+ $ mkdir ~/bin
+ $ PATH=~/bin:$PATH
+
+ - Download the Repo script and ensure it is executable:
+
+ $ curl http://android.git.kernel.org/repo > ~/bin/repo
+ $ chmod a+x ~/bin/repo
+
+
+## Initializing a Repo client ##
+
+After installing Repo, set up your client to access the android source repository:
+
+ - Create an empty directory to hold your working files:
+
+ $ mkdir WORKING_DIRECTORY
+ $ cd WORKING_DIRECTORY
+
+ - Run `repo init` to bring down the latest version of Repo with all its most recent bug fixes. You must specify a URL for the manifest, which specifies where the various repositories included in the Android source will be placed within your working directory.
+
+ $ repo init -u git://android.git.kernel.org/platform/manifest.git
+
+ To check out a branch other than "master", specify it with -b:
+
+ $ repo init -u git://android.git.kernel.org/platform/manifest.git -b froyo
+
+ - When prompted, please configure Repo with your real name and email address. To use the Gerrit code-review tool, you will need an email address that is connected with a [registered Google account](http://www.google.com/accounts). Make sure this is a live address at which you can receive messages. The name that you provide here will show up in attributions for your code submissions.
+
+A successful initialization will end with a message stating that Repo is initialized in your working directory. Your client directory should now contain a `.repo` directory where files such as the manifest will be kept.
+
+
+
+## Getting the files ##
+
+To pull down files to your working directory from the repositories as specified in the default manifest, run
+
+ $ repo sync
+
+The Android source files will be located in your working directory under their project names. The initial sync operation will take several minutes to complete. For more about `repo sync` and other Repo commands, see [Using Repo and Git](git-repo.html).
+
+
+## Verifying Git Tags ##
+
+Load the following public key into your GnuPG key database. The key is used to sign annotated tags that represent releases.
+
+ $ gpg --import
+
+Copy and paste the key(s) below, then enter EOF (Ctrl-D) to end the input and process the keys.
+
+ -----BEGIN PGP PUBLIC KEY BLOCK-----
+ Version: GnuPG v1.4.2.2 (GNU/Linux)
+ mQGiBEnnWD4RBACt9/h4v9xnnGDou13y3dvOx6/t43LPPIxeJ8eX9WB+8LLuROSV
+ lFhpHawsVAcFlmi7f7jdSRF+OvtZL9ShPKdLfwBJMNkU66/TZmPewS4m782ndtw7
+ 8tR1cXb197Ob8kOfQB3A9yk2XZ4ei4ZC3i6wVdqHLRxABdncwu5hOF9KXwCgkxMD
+ u4PVgChaAJzTYJ1EG+UYBIUEAJmfearb0qRAN7dEoff0FeXsEaUA6U90sEoVks0Z
+ wNj96SA8BL+a1OoEUUfpMhiHyLuQSftxisJxTh+2QclzDviDyaTrkANjdYY7p2cq
+ /HMdOY7LJlHaqtXmZxXjjtw5Uc2QG8UY8aziU3IE9nTjSwCXeJnuyvoizl9/I1S5
+ jU5SA/9WwIps4SC84ielIXiGWEqq6i6/sk4I9q1YemZF2XVVKnmI1F4iCMtNKsR4
+ MGSa1gA8s4iQbsKNWPgp7M3a51JCVCu6l/8zTpA+uUGapw4tWCp4o0dpIvDPBEa9
+ b/aF/ygcR8mh5hgUfpF9IpXdknOsbKCvM9lSSfRciETykZc4wrRCVGhlIEFuZHJv
+ aWQgT3BlbiBTb3VyY2UgUHJvamVjdCA8aW5pdGlhbC1jb250cmlidXRpb25AYW5k
+ cm9pZC5jb20+iGAEExECACAFAknnWD4CGwMGCwkIBwMCBBUCCAMEFgIDAQIeAQIX
+ gAAKCRDorT+BmrEOeNr+AJ42Xy6tEW7r3KzrJxnRX8mij9z8tgCdFfQYiHpYngkI
+ 2t09Ed+9Bm4gmEO5Ag0ESedYRBAIAKVW1JcMBWvV/0Bo9WiByJ9WJ5swMN36/vAl
+ QN4mWRhfzDOk/Rosdb0csAO/l8Kz0gKQPOfObtyYjvI8JMC3rmi+LIvSUT9806Up
+ hisyEmmHv6U8gUb/xHLIanXGxwhYzjgeuAXVCsv+EvoPIHbY4L/KvP5x+oCJIDbk
+ C2b1TvVk9PryzmE4BPIQL/NtgR1oLWm/uWR9zRUFtBnE411aMAN3qnAHBBMZzKMX
+ LWBGWE0znfRrnczI5p49i2YZJAjyX1P2WzmScK49CV82dzLo71MnrF6fj+Udtb5+
+ OgTg7Cow+8PRaTkJEW5Y2JIZpnRUq0CYxAmHYX79EMKHDSThf/8AAwUIAJPWsB/M
+ pK+KMs/s3r6nJrnYLTfdZhtmQXimpoDMJg1zxmL8UfNUKiQZ6esoAWtDgpqt7Y7s
+ KZ8laHRARonte394hidZzM5nb6hQvpPjt2OlPRsyqVxw4c/KsjADtAuKW9/d8phb
+ N8bTyOJo856qg4oOEzKG9eeF7oaZTYBy33BTL0408sEBxiMior6b8LrZrAhkqDjA
+ vUXRwm/fFKgpsOysxC6xi553CxBUCH2omNV6Ka1LNMwzSp9ILz8jEGqmUtkBszwo
+ G1S8fXgE0Lq3cdDM/GJ4QXP/p6LiwNF99faDMTV3+2SAOGvytOX6KjKVzKOSsfJQ
+ hN0DlsIw8hqJc0WISQQYEQIACQUCSedYRAIbDAAKCRDorT+BmrEOeCUOAJ9qmR0l
+ EXzeoxcdoafxqf6gZlJZlACgkWF7wi2YLW3Oa+jv2QSTlrx4KLM=
+ =Wi5D
+ -----END PGP PUBLIC KEY BLOCK-----
+
+After importing the keys, you can verify any tag with
+
+ $ git tag -v TAG_NAME
+
+
+# Next: Build the code #
+
+You now have a complete local copy of the Android codebase. Continue on to [building](building.html)....
diff --git a/src/source/flashing.md b/src/source/flashing.md
new file mode 100644
index 0000000..fb6c516
--- /dev/null
+++ b/src/source/flashing.md
@@ -0,0 +1,19 @@
+# Flashing #
+
+To flash a device, you will need to use `fastboot`. Place the device in fastboot mode either manually by holding the appropriate key combination at boot, or from the shell with
+
+ $ adb reboot bootloader
+
+Once the device is in fastboot mode, run
+
+ $ fastboot flashall -w
+
+The `-w` option wipes the `/data` partition on the device; this is useful for your first time flashing a particular device, but is otherwise unnecessary.
+
+# Emulating #
+
+To run the emulator, type
+
+ $ emulator
+
+
diff --git a/src/source/git-resources.md b/src/source/git-resources.md
new file mode 100644
index 0000000..9012872
--- /dev/null
+++ b/src/source/git-resources.md
@@ -0,0 +1,13 @@
+# Git Resources #
+
+For further information on Git, check out these excellent off-site resources:
+
+- The [Git Community Book](http://book.git-scm.com) (maintained by Scott Chacon)
+
+- [Git Wiki](http://git.or.cz/gitwiki/FrontPage)
+
+- [Git Manual Page](http://www.kernel.org/pub/software/scm/git/docs)
+
+- [GitCasts](http://www.gitcasts.com) (Git how-to videos)
+
+
diff --git a/src/source/index.md b/src/source/index.md
new file mode 100644
index 0000000..742a24a
--- /dev/null
+++ b/src/source/index.md
@@ -0,0 +1,35 @@
+# Get Involved #
+
+Thanks for your interest in Android! Here are some ways you can get involved
+and help us improve Android. For background on the Android project and our
+goals, check out the [Project Philosophy page](philosophy.html).
+
+## Report Bugs ##
+
+One of the easiest and most effective ways you can help improve Android is
+to file bugs. For more information, visit the [Reporting Bugs](report-bugs.html) page.
+
+Please note that we can't guarantee that any particular bug will be fixed in
+any particular release. To see what happens to your bug once you report it,
+read [Life of a Bug](life-of-a-bug.html).
+
+## Develop Apps ##
+
+We created Android so that all developers can distribute their applications
+to users on an open platform. One of the best ways you can help Android is to
+write cool apps that users love!
+
+To get started, visit [developer.android.com](http://developer.android.com). This site
+provides the information and tools you need to write applications for
+compatible Android devices, using the SDK.
+
+## Contribute to the Code ##
+
+Code is King. We'd love to review any changes you submit, so please check
+out the source, pick a bug or feature, and get coding. Note that the smaller
+and more targetted your patch submissions, the easier it will be for us to
+review them.
+
+You can get started with Android by learning about the [Life of a Patch](life-of-a-patch.html),
+and by learning about `git`, `repo`, and other tools using the links to the left.
+If you need help along the way, you can join our [discussion groups](/community/index.html).
diff --git a/src/source/initializing.md b/src/source/initializing.md
new file mode 100644
index 0000000..e08a487
--- /dev/null
+++ b/src/source/initializing.md
@@ -0,0 +1,162 @@
+# Initializing a Build Environment #
+
+The "Getting Started" section describes how to set up your local work environment, how to use Repo to get the Android files, and how to build the files on your machine. To build the Android source files, you will need to use Linux or Mac OS. Building under Windows is not currently supported.
+
+*Note: The source is approximately 2.6GB in size. You will need 10GB free to complete the build.*
+
+For an overview of the entire code-review and code-update process, see [Life of a Patch](life-of-a-patch.html).
+
+To see snapshots and histories of the files available in the public Android repositories, visit the [GitWeb](http://android.git.kernel.org) web interface.
+
+
+
+# Setting up a Linux build environment #
+
+The Android build is routinely tested in house on recent versions of Ubuntu (10.04 and later), but most distributions should have the required build tools available. Reports of successes or failures on other distributions are welcome.
+
+*Note: It is also possible to build Android in a virtual machine. If you are running Linux in a virtual machine, you will need at least 8GB of RAM/swap and 12GB or more of disk space in order to build the Android tree.*
+
+In general you will need:
+
+ - Python 2.4 -- 2.7, which you can download from [python.org](http://www.python.org/download/).
+
+ - JDK 6 if you wish to build Gingerbread or newer; JDK 5 for Froyo or older. You can download both from [java.sun.com](http://java.sun.com/javase/downloads/).
+
+ - Git 1.5.4 or newer. You can find it at [git-scm.com](http://git-scm.com/download).
+
+ - (optional) Valgrind, a tool that will help you find memory leaks, stack corruption, array bounds overflows, etc. Download from [valgrind.org](http://valgrind.org/downloads/current.html).
+
+Detailed instructions for Ubuntu 10.04+ follow.
+
+## Installing the JDK ##
+
+The Sun JDK is no longer in Ubuntu's main package repository. In order to download it, you need to add the appropriate repository and indicate to the system which JDK should be used.
+
+Java 6: for Gingerbread and newer
+
+ $ sudo add-apt-repository "deb http://archive.canonical.com/ lucid partner"
+ $ sudo add-apt-repository "deb-src http://archive.canonical.com/ubuntu lucid partner"
+ $ sudo apt-get update
+ $ sudo apt-get install sun-java6-jdk
+
+Java 5: for Froyo and older
+
+ $ sudo add-apt-repository "deb http://archive.ubuntu.com/ubuntu dapper main multiverse"
+ $ sudo add-apt-repository "deb http://archive.ubuntu.com/ubuntu dapper-updates main multiverse"
+ $ sudo apt-get update
+ $ sudo apt-get install sun-java5-jdk
+
+## Installing required packages ##
+
+To set up your development environment, install the following required packages:
+
+ $ sudo apt-get install git-core gnupg flex bison gperf build-essential zip curl zlib1g-dev libc6-dev
+ lib32ncurses5-dev ia32-libs x11proto-core-dev libx11-dev lib32readline5-dev lib32z-dev
+
+For building Froyo or an older release on a 64-bit system, several other packages are necessary to establish a 32-bit build environment:
+
+ $ sudo apt-get install gcc-multilib g++-multilib libc6-i386 libc6-dev-i386
+
+## Configuring USB Access ##
+
+Under GNU/linux systems (and specifically under Ubuntu systems),
+regular users can't directly access USB devices by default. The
+system needs to be configured to allow such access.
+
+The recommended approach is to create a file
+`/etc/udev/rules.d/51-android.rules` (as the root user) and to copy
+the following lines in it. <username> must be replaced by the
+actual username of the user who is authorized to access the phones
+over USB.
+
+ # adb protocol on passion (Nexus One)
+ SUBSYSTEM=="usb", ATTR{idVendor}=="18d1", ATTR{idProduct}=="4e12", MODE="0600", OWNER="<username>"
+ # fastboot protocol on passion (Nexus One)
+ SUBSYSTEM=="usb", ATTR{idVendor}=="0bb4", ATTR{idProduct}=="0fff", MODE="0600", OWNER="<username>"
+ # adb protocol on crespo (Nexus S)
+ SUBSYSTEM=="usb", ATTR{idVendor}=="18d1", ATTR{idProduct}=="4e22", MODE="0600", OWNER="<username>"
+ # fastboot protocol on crespo (Nexus S)
+ SUBSYSTEM=="usb", ATTR{idVendor}=="18d1", ATTR{idProduct}=="4e20", MODE="0600", OWNER="<username>"
+
+Those new rules take effect the next time a device is plugged in.
+It might therefore be necessary to unplug the device and plug it
+back into the computer.
+
+This is known to work on both Ubuntu Hardy Heron (8.04.x LTS) and
+Lucid Lynx (10.04.x LTS). Other versions of Ubuntu or other
+variants of GNU/linux might require different configurations.
+
+
+# Setting up a Mac OS X build environment #
+
+To build the Android files in a Mac OS environment, you need an Intel/x86 machine running MacOS 10.4 (Tiger), 10.5 (Leopard), or 10.6 (Snow Leopard). The Android build system and tools do not support the obsolete PowerPC architecture.
+
+Android must be built on a case-sensitive file system because the sources contain files that differ only in case. We recommend that you build Android on a partition that has been formatted with the journaled file system HFS+. HFS+ is required to successfully build Mac OS applications such as the Android Emulator for OS X.
+
+## Creating a case sensitive disk image ##
+
+If you want to avoid partitioning/formatting your hard drive, you can use a case-sensitive disk image instead. To create the image, launch Disk Utility and select "New Image". A size of 12 GB should be sufficient to complete the build. Be sure to select "case sensitive, journaled" as the volume format.
+
+This will create a .dmg file which, once mounted, acts as a drive with the required formatting for Android development. For a disk image named "android.dmg" stored in your home directory, you can add the following to your `~/.bash_profile` to mount the image when you execute "mountAndroid":
+
+ # mount the android file image
+ function mountAndroid{ hdiutil attach ~/android.dmg-mountpoint /Volumes/android; }
+
+Once mounted, you'll do all your work in the "android" volume. You can eject it (unmount it) just like you would with an external drive.
+
+## Installing required packages ##
+
+- Install XCode from [the Apple developer site](http://developer.apple.com/). We recommend version 3.0 or newer. If you are not already registered as an Apple developer, you will have to create an Apple ID in order to download.
+
+- Install MacPorts from [macports.org](http://www.macports.org/install.php).
+
+ *Note: Make sure that `/opt/local/bin` appears in your path BEFORE `/usr/bin`. If not, add*
+
+ export PATH=/opt/local/bin:$PATH
+
+ *to your `~/.bash_profile`.*
+
+- Get make, git, and GPG packages from MacPorts:
+
+ $ POSIXLY_CORRECT=1 sudo port install gmake libsdl git-core gnupg
+
+ If using Mac OS 10.4, also install bison:
+
+ $ POSIXLY_CORRECT=1 sudo port install bison
+
+## Reverting from make 3.82 ##
+
+There is a bug in gmake 3.82 that prevents android from building. You can install version 3.81 using MacPorts by taking the following steps:
+
+- Edit `/opt/local/etc/macports/sources.conf` and a line that says
+
+ file:///Users/Shared/dports
+
+ above the rsync line. Then create this directory:
+
+ $ mkdir /Users/Shared/dports
+
+- In the new `dports` directory, run
+
+ $ svn co --revision 50980 http://svn.macports.org/repository/macports/trunk/dports/devel/gmake/ devel/gmake/
+
+- Create a port index for your new local repository:
+
+ $ portindex /Users/Shared/dports
+
+- Finally, install the old version of gmake with
+
+ $ sudo port install gmake @3.81
+
+## Setting a file descriptor limit ##
+
+On MacOS the default limit on the number of simultaneous file descriptors open is too low and a highly parallel build process may exceed this limit.
+
+To increase the cap, add the following lines to your `~/.bash_profile`:
+
+ # set the number of open files to be 1024
+ ulimit -S -n 1024
+
+# Next: Download the source #
+
+Your build environment is good to go! Proceed to [downloading the source](downloading.html)....
diff --git a/src/source/life-of-a-bug.md b/src/source/life-of-a-bug.md
new file mode 100644
index 0000000..8ed2cae
--- /dev/null
+++ b/src/source/life-of-a-bug.md
@@ -0,0 +1,157 @@
+# Life of a Bug #
+
+The Android Open Source project maintains a public issue tracker where you
+can report bugs and request features for the Android software stack. (For
+details on this issue tracker, please see the [Reporting Bugs](report-bugs.html) page).
+Reporting bugs is great (thank you!), but what happens to a bug report once
+you file it? This page describes the Life of a Bug.
+
+*lease note: the the Android Open Source Project (AOSP) issue tracker is
+intended only for bugs and feature requests related to the Android software
+stack. Because many users find their way here looking for the Google apps for
+Android (such as Gmail and so on), we have components set up for their
+convenience. However, these apps are not part of Android, and any issues
+reported on these components are not guaranteed to to receive attention.
+Most notably, to report issues related to Android Market, you should visit the
+[Android Market Support Forum](http://www.google.com/support/forum/p/Android+Market?hl=en).
+
+Here's the life of a bug, in a nutshell:
+
+1. A bug is filed, and has the state "New".
+
+1. An AOSP contributor periodically reviews and triages bugs. Bugs are
+triaged into one of four "buckets": New, Open, No-Action, or Resolved.
+
+1. Each bucket includes a number of states that provide more detail on the
+fate of the issue.
+
+1. Bugs in the "Resolved" bucket will eventually be included in a future
+release of the Android software.
+
+# Bucket Details #
+
+Here is some additional information on each bucket, what it means, and how
+it's handled.
+
+## New Issues ##
+
+New issues include bug reports that are not yet being acted upon. The two
+states are:
+
+- *New:*
+ The bug report has not yet been triaged (that is, reviewed by an AOSP contributor.)
+
+- *NeedsInfo:*
+ The bug report has insufficient information to act
+upon. The person who reported the bug needs to provide additional detail
+before it can be triaged. If enough time passes and no new information is
+provided, the bug may be closed by default, as one of the No-Action
+states.
+
+## Open Issues ##
+
+This bucket contains bugs that need action, but which are still
+unresolved, pending a change to the source code.
+
+- *Unassigned:*
+ The bug report has been recognized as an adequately
+detailed report of a legitimate issue, but has not yet been assigned to an
+AOSP contributor to be fixed. Typically, bugs in this state are considered low
+priority, at least insofar that if they were high priority, they'd be assigned
+to a contributor.
+
+- *Reviewed:*
+ Like *Unassigned*, but the issue
+represented is being tracked in a separate bug database. For example, the bug
+might have been reported via an internal bug-tracking system,
+which is considered the "master" copy. (For instance, Google maintains one
+such private issue tracker, intended primarily for bugs which contain
+sensitive information which can't be revealed publicly.)
+
+- *Assigned:*
+ Like *Unassigned*, but the bug has been
+actually assigned to a specific contributor to fix.
+
+Typically, a given bug will start in *Unassigned*, where it
+will remain until it is associated with a specific upcoming release, at which
+point it will enter *Reviewed* or *Assigned*. However,
+note that this isn't a guarantee, and it's not uncommon for bugs to go from
+*Unassigned* to one of the Resolved states.
+
+In general, if a bug is in one of these Open states, the AOSP team has
+recognized it as a legitimate issue and will fix it according to the product
+priorities and milestones. However, it's impossible to guarantee a fix in time
+for any particular release.
+
+## No-Action Issues ##
+
+This bucket contains bugs that have for one reason or another been
+determined to not require any action.
+
+- *Spam:*
+ A kind soul sent us some delicious pork products, that we,
+regrettably, do not want.
+
+- *Question:*
+ Someone mistook the issue tracker for a help forum.
+(This is not as uncommon as you might think: many users whose native language
+isn't English misunderstand the site and make this mistake.)
+
+- *Unreproducible:*
+ An AOSP contributor attempted to reproduce the
+behavior described, and was unable to do so. This sometimes means that the bug
+is legitimate but simply rare or difficult to reproduce, and sometimes means
+that the bug was fixed in a later release.
+
+- *WorkingAsIntended:*
+ An AOSP contributor has determined that the
+behavior described isn't a bug, but is the intended behavior. This state is
+also commonly referred to as "WAI".
+
+- *Declined:*
+ This is like *WorkingAsIntended*, except
+typically used for feature requests instead of bugs. That is, an AOSP
+contributor has determined that the request is not going to be implemented in
+Android.
+
+## Resolved Issues ##
+
+This bucket contains bugs that have had action taken, and are now
+considered resolved.
+
+- *FutureRelease:*
+ This bug has been fixed (or feature implemented) in
+a source tree, but has not yet been included in a formal Android
+platform release. (Note that this may also include fixes that exist in a
+private source tree that has not yet been contributed to a public
+tree.)
+
+- *Released:*
+ This bug has been fixed, and is included in a formal
+Android platform release. When this state is set, we try to also set a
+property indicating which release it was fixed in.
+
+- *Duplicate:*
+ This bug is a duplicate of another, existing bug report.
+
+# Other Stuff #
+
+The states and lifecycle above are how we generally try to track software.
+However, Android contains a lot of software and gets a correspondingly large
+number of bugs. As a result, sometimes bugs don't make it through all the
+states in a formal progression. We do try to keep the system up to date, but
+we tend to do so in periodic "bug sweeps" where we review the database and
+make updates.
+
+Since the AOSP is essentially constantly evolving, we do make tweaks to
+the list of bug states and the lifecycle described above. When we do this,
+however, we'll be sure to update this page as well.
+
+Finally, you should be aware that for a variety of reasons, there are
+actually multiple issue trackers for Android-related issues. The
+[Google Code Project Hosting Issue Tracker](http://code.google.com/p/android/issues/list)
+is the *only* official public issue tracker; however,
+Google also maintains a private issue tracker, own, as do most OEMs. We try to
+keep the public issue tracker in sync with private issue trackers
+wherever possible, but in cases where confidential information and security
+issues are involved, this isn't always possible.
diff --git a/src/source/life-of-a-patch.md b/src/source/life-of-a-patch.md
new file mode 100644
index 0000000..95cb96d
--- /dev/null
+++ b/src/source/life-of-a-patch.md
@@ -0,0 +1,11 @@
+# Life of a Patch #
+
+The Android Open Source Project (AOSP) uses a web-based code review tool
+known as "gerrit". The image below is a flowchart that details what happens to
+a patch, once it's been written. Though it may appear complex, the majority of
+the steps below are performed in the web application.
+
+For full instructions on how to get set up to use gerrit and git, please
+see the [Submitting Patches](submit-patches.html) page.
+
+<img src="/images/workflow-0.png"/>
diff --git a/src/source/overview.md b/src/source/overview.md
new file mode 100644
index 0000000..67394b8
--- /dev/null
+++ b/src/source/overview.md
@@ -0,0 +1,35 @@
+# Android 2.1 Platform #
+
+<p>Our sister site, <a
+href="http://developer.android.com/">http://developer.android.com/</a>,
+includes feature overviews of the various Android platform versions.
+The links below will take you to developer.android.com where you can view this
+information.</p>
+<p>The links below will navigate you away from this site.</p>
+<h3><a href="http://developer.android.com/sdk/android-2.3-highlights.html">Android 2.3</a></h3>
+<p>Android 2.3 corresponded to the "Gingerbread" milestone branch, and has an API level of 9.</p>
+<h3><a href="http://developer.android.com/sdk/android-2.2-highlights.html">Android 2.2</a></h3>
+<p>Android 2.2 corresponded to the "FroYo" milestone branch, and has an API level of 8.</p>
+<h3><a href="http://developer.android.com/sdk/android-2.0-highlights.html">Android 2.1</a></h3>
+<p>Android 2.1 corresponded to the "Eclair" milestone branch, and has an API level of
+7.</p>
+<p>The Eclair branch was also used for 2.0 and 2.0.1; however, both of those
+releases were quickly obsoleted by the version 2.1 Eclair release. As Android
+2.1 includes key bug fixes and improvements not present in 2.0/2.0.1, only
+Android 2.1 should be used for new devices. As there is no compatibility
+program for 2.0 or 2.0.1, the officially compatible Eclair-based release is Android
+2.1. (The linked document refers to Android 2.0, because there were
+no new platform features added in 2.1.)</p>
+<h3><a href="http://developer.android.com/sdk/android-1.6-highlights.html">Android 1.6</a></h3>
+<p>Android 1.6 corresponded to the "Donut" milestone branch, and has an API level of
+4.</p>
+<h3><a href="http://developer.android.com/sdk/android-1.5-highlights.html">Android 1.5</a></h3>
+<p>Android 1.5 corresponded to the "Cupcake" milestone branch, and has an API
+level of 3.</p>
+<h3><a href="http://developer.android.com/sdk/android-1.1.html">Android 1.1</a></h3>
+<p>Android 1.1 has an API level of 2. Android 1.1 was known as
+"Petit Four" internally, though this name was not used officially.</p>
+<h3>Android 1.0</h3>
+<p>was the first release of Android, and has an API
+level of 1. Since it was the first released version of Android, no platform
+highlights were prepared for this release.</p>
diff --git a/src/source/report-bugs.md b/src/source/report-bugs.md
new file mode 100644
index 0000000..3cca08d
--- /dev/null
+++ b/src/source/report-bugs.md
@@ -0,0 +1,123 @@
+# Report Bugs #
+
+Thanks for your interest in Android! One of the best ways you can help us
+improve Android is to let us know about any problems you find with it.
+
+First, though: if you think you've found a security vulnerability,
+*please don't use the forms below*. Using the public forms below may
+allow anyone to see your report, which may put users at risk until the bug is
+fixed. Instead, please report security bugs to our security team by emailing
+<a href="mailto:security@android.com">security@android.com</a>. We believe in
+responsible disclosure of security vulnerabilities, and will give you proper
+attribution for any issues you report.
+
+Here's how to report non-security bugs:
+
+- [Search for your bug](http://code.google.com/p/android/issues/advsearch) to see if anyone has already reported it.
+
+- If you find your issue and it's important to you, star it! That's how we know which bugs are most important to fix.
+
+- If no one's reported your bug, file the bug. You can use one of these templates:
+
+ - [Bug in your Device](http://code.google.com/p/android/issues/entry?template=User%20bug%20report) - use this if you are a user reporting a bug in a device you own
+
+ - [Bug in the Software](http://code.google.com/p/android/issues/entry?template=Developer%20bug%20report) - use this if you found a bug in the course of developing an app
+
+ - [Feature Request](http://code.google.com/p/android/issues/entry?template=Feature%20request) - use this for a feature you'd like to see in a future verison
+
+Please note that we can't guarantee that any particular bug can be fixed in
+any particular release. To see what happens to your bug once you report it,
+read [Life of a Bug](life-of-a-bug.html).
+
+In general, please put as much info in bugs as you can. Just a one liner
+telling us something isn't working is usually useless, and will probably be
+closed without any action. The more detail you provide, the more likely your
+issue is to be resolved. Below, there are some examples of a good bug report
+and a poor bug report.
+
+## A Poor Bug Report ##
+ Title: Error message
+
+ When running Eclipse I get an "Internal Error" that says "See the .log file for more details".
+
+ Steps to reproduce:
+ Happens when "Object o = null". Doesn't happen when changed to "Object o".
+
+ Expected results:
+ I wouldn't get the error message--would work with Object o = null.
+
+ Observed results:
+ See above.
+
+This is a poor bug report because it doesn't provide any context for the
+issue; is it a problem in the Dalvik virtual machine, the core framework, or
+something else? It also doesn't provide any code or hint on how to reproduce
+it. In other words, this bug report doesn't provide enough information for
+anyone to take action on, so it would be ignored.
+
+## A Good Bug Report ##
+
+ Title: Stepping over "Object o = null" causes Eclipse "Internal Error"
+
+ Interesting bug, while using Eclipse 3.3.1.1 with m37a of android and the following code:
+
+ package com.saville.android;
+
+ import android.app.Activity;
+ import android.os.Bundle;
+ import android.util.Log;
+
+ public class TestObjectNull extends Activity {
+ /** Called when the activity is first created. */
+ @Override
+ public void onCreate(Bundle icicle) {
+ super.onCreate(icicle);
+ setContentView(R.layout.main);
+
+ Object o = null;
+
+ o = "hi";
+
+ Log.v(TAG, "o=" + o);
+ }
+
+ static final String TAG = "TestObjectNull";
+ }
+
+ Eclipse indicates an "Internal Error" with "See the .log file for more
+ details" and then asks if I want to exit the workbench. This occurs when I
+ place a break point on "setContentView(R.layout.main);" and then single
+ step over "Object o = null;"
+
+ If I change "Object o = null;" to "Object o" all is well.
+
+ The last lines of the .log file are:
+
+ !ENTRY org.eclipse.core.jobs 4 2 2008-01-01 13:04:15.825
+ !MESSAGE An internal error occurred during: "has children update".
+ !STACK 0
+ java.lang.InternalError: Invalid signature: "<null>"
+ at
+ org.eclipse.jdi.internal.TypeImpl.signatureToTag(TypeImpl.java:307)
+ at
+ org.eclipse.jdi.internal.LocalVariableImpl.tag(LocalVariableImpl.java:185)
+ at
+ org.eclipse.jdi.internal.StackFrameImpl.getValues(StackFrameImpl.java:128)
+ at
+ org.eclipse.jdi.internal.StackFrameImpl.getValue(StackFrameImpl.java:73)
+ at
+ org.eclipse.jdt.internal.debug.core.model.JDILocalVariable.retrieveValue(JDILocalVariable.java:57)
+ at
+ org.eclipse.jdt.internal.debug.core.model.JDIVariable.getCurrentValue(JDIVariable.java:66)
+ at
+ org.eclipse.jdt.internal.debug.core.model.JDIVariable.getValue(JDIVariable.java:88)
+ at
+ org.eclipse.debug.internal.ui.model.elements.VariableContentProvider.hasChildren(VariableContentProvider.java:62)
+ at
+ org.eclipse.jdt.internal.debug.ui.variables.JavaVariableContentProvider.hasChildren(JavaVariableContentProvider.java:73)
+ at
+ org.eclipse.debug.internal.ui.model.elements.ElementContentProvider.updateHasChildren(ElementContentProvider.java:223)
+ at
+ org.eclipse.debug.internal.ui.model.elements.ElementContentProvider$3.run(ElementContentProvider.java:200)
+ at org.eclipse.core.internal.jobs.Worker.run(Worker.java:55)
+
diff --git a/src/source/sidebar.md b/src/source/sidebar.md
new file mode 100644
index 0000000..e34e247
--- /dev/null
+++ b/src/source/sidebar.md
@@ -0,0 +1,31 @@
+# Getting Started #
+
+- [Initializing the Build Environment](initializing.html)
+- [Downloading the Source](downloading.html)
+- [Building and Running](building.html)
+
+# Navigating the Source #
+
+- [Platform Overview](overview.html)
+- [Branches & Releases](code-lines.html)
+- [Build Numbers](build-numbers.html)
+- [Browse Source](http://android.git.kernel.org)
+
+# Contributing #
+
+- [Life of a Patch](life-of-a-patch.html)
+- [Submitting Patches](submit-patches.html)
+- [Life of a Bug](life-of-a-bug.html)
+- [Reporting Bugs](report-bugs.html)
+
+# Reference #
+
+- [Version Control](version-control.html)
+ - [Repo Commands](using-repo.html)
+ - [Git Resources](git-resources.html)
+- [Using Eclipse](using-eclipse.html)
+- [Code Style Guidelines](code-style.html)
+- [FAQs](/faqs.html)
+
+
+
diff --git a/src/source/submit-patches.md b/src/source/submit-patches.md
new file mode 100644
index 0000000..01e7430
--- /dev/null
+++ b/src/source/submit-patches.md
@@ -0,0 +1,131 @@
+# Submitting Patches #
+
+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 will need to set up your
+local working environment and get the Android source files. For instructions,
+follow the "Getting Started" section [here](downloading.html).
+
+- For details about Repo and Git, see [Version Control](version-control.html).
+
+- For information about the different roles you can play within the Android
+Open Source community, see [Project roles](/about/roles.html).
+
+- If you plan to contribute code to the Android platform, be sure to read
+the [AOSP's licensing information](/about/licenses.html).
+
+- Note that changes to some of the upstream projects used by Android should be
+made directly to that project, as described in [Upstream Projects](#upstream-projects).
+
+## Patch Etiquette ##
+
+### Writing patch descriptions ###
+
+Each change list description will be pushed to the public AOSP repository. Please follow our guidelines for writing change descriptions in order to ensure your change is reviewed and approved.
+
+- Start with a one-line summary, 50-60 characters max, followed by a blank line. This format is used by git and gerrit for various displays.
+
+- The description should focus on what issue it solves, and how it solves it. The second part is somewhat optional when implementing new features, though desirable.
+
+- The description should be self-contained. It should not rely on people having access to any other information.
+
+- The description should be reasonably descriptive. You've spent a few hours or a few days working on your change so you can spend 5 minutes writing a proper description. Maybe write it while you do a final compile before submitting.
+
+## Using the Gerrit code-review tool ##
+
+You can open Gerrit by visiting whatever URL is returned to you from the repo upload command,
+or by visiting [https://review.android.com](https://review.source.android.com)
+
+### Viewing the status of uploaded changes ###
+
+To check the status of a change that you uploaded, open [Gerrit](https://review.source.android.com/mine),
+sign in, and click MyChanges.
+
+### Reviewing a change ###
+
+If you are assigned to be the Approver for a change, you need to determine the following:
+
+- Does this change fit within this project's stated purpose?
+
+- Is this change valid within the project's existing architecture?
+
+- Does this change introduce design flaws that will cause problems in the future?
+
+- Does this change follow the best practices that have been established for this project?
+
+- Is this change a good way to perform the described function?
+
+- Does this change introduce any security or instability risks?
+
+If you approve of the change, mark it with LGTM ("Looks Good to Me") within Gerrit.
+
+### Verifying a change ###
+
+If you are assigned to be the Verifier for a change, you need to do the following:
+
+- Patch the change into your local client using one of the Download commands.
+
+- Build and test the change.
+
+- Within Gerrit use Publish Comments to mark the commit as "Verified" or "Fails," and add a message explaining what problems were identified.
+
+### Viewing diffs and comments ###
+
+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."
+
+### Adding comments ###
+
+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.
+
+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.
+
+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.
+
+### 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. 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.
+
+### Downloading changes from Gerrit ###
+
+A submission that has been verified and merged will be downloaded with the next `repo sync`. If you wish to download a specific change that has not yet been approved, run
+
+ $ repo download TARGET CHANGE
+
+where TARGET is the local directory into which the change should be downloaded and CHANGE is the
+change number as listed in [Gerrit](https://review.source.android.com/). For more information,
+see the [Repo reference](/source/using-repo.html).
+
+### How do I become a Verifier or Approver? ###
+
+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 [Project Roles](/about/roles.html).
+
+## Using GitWeb to track patch histories ##
+
+To view snapshots of the files that are in the public Android repositories and view file histories, use the [Android instance of GitWeb](http://android.git.kernel.org/).
+
+<a name="upstream-projects"></a>
+
+## Upstream Projects ##
+
+Android makes use of a number of other open-source projects, such as the Linux kernel and WebKit, as described in
+[Branches and Releases](/source/code-lines.html). 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.
+
+### WebKit ###
+
+All changes to the WebKit project at `external/webkit` should be made
+upstream at [webkit.org](http://www.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](http://webkit.org/coding/contributing.html) for details.
+
+### V8 ###
+
+All changes to the V8 project at `external/v8` should be submitted upstream at
+[code.google.com/p/v8](http://code.google.com/p/v8). See [Contributing to V8](http://code.google.com/p/v8/wiki/Contributing)
+for details.
+
diff --git a/src/source/using-eclipse.md b/src/source/using-eclipse.md
new file mode 100644
index 0000000..21f5618
--- /dev/null
+++ b/src/source/using-eclipse.md
@@ -0,0 +1,175 @@
+# Using Eclipse #
+
+This document will help you set up the Eclipse IDE for Android platform development.
+
+*Note: if you are looking for information on how to use
+Eclipse to develop applications that run on Android, this is not the right
+page for you. You probably would find [the Eclipse page on
+developer.android.com](http://developer.android.com/sdk/eclipse-adt.html) more useful.*
+
+## Basic setup ##
+
+First, it's important to make sure the regular Android development system is set up.
+
+ cd /path/to/android/root
+ make
+
+**Important**: You will still be using `make` to build the files you will actually run (in the emulator or on a device). You will be using Eclipse to edit files and verify that they compile, but when you want to run something you will need to make sure files are saved in Eclipse and run `make` in a shell. The Eclipse build is just for error checking.
+
+Eclipse needs a list of directories to search for Java files. This is called the "Java Build Path" and can be set with the `.classpath` file. We have a sample version to start you off.
+
+ cd /path/to/android/root
+ cp development/ide/eclipse/.classpath .
+ chmod u+w .classpath
+
+Now edit that copy of `.classpath`, if necessary.
+
+### Increase Eclipse's Memory Settings ###
+
+The Android project is large enough that Eclipse's Java VM sometimes runs out of memory while compiling it. Avoid this problem by editing the the `eclipse.ini` file. On Apple OSX the eclipse.ini file is located at
+
+ /Applications/eclipse/Eclipse.app/Contents/MacOS/eclipse.ini
+
+Memory-related defaults (as of Eclipse 3.4):
+
+ -Xms40m
+ -Xmx256m
+ -XX:MaxPermSize=256m
+
+Recommended settings for Android development:
+
+ -Xms128m
+ -Xmx512m
+ -XX:MaxPermSize=256m
+
+These settings set Eclipse's minimum Java heap size to 128MB, set the maximum Java heap size to 512MB, and keep the maximum permanent generation size at the default of 256MB.
+
+Now start Eclipse:
+
+ eclipse
+
+Now create a project for Android development:
+
+1. If Eclipse asks you for a workspace location, choose the default.
+
+2. If you have a "Welcome" screen, close it to reveal the Java perspective.
+
+3. File > New > Java Project
+
+4. Pick a project name, "android" or anything you like.
+
+5. Select "Create project from existing source", enter the path to your Android root directory, and click Finish.
+
+6. Wait while it sets up the project. (You'll see a subtle progress meter in the lower right corner.)
+
+Once the project workspace is created, Eclipse should start building. In theory, it should build with no errors and you should be set to go. If necessary, uncheck and re-check Project Build Automatically to force a rebuild.
+
+*Note:* Eclipse sometimes likes to add an `import android.R` statement at the top of your files that use resources, especially when you ask eclipse to sort or otherwise manage imports. This will cause your make to break. Look out for these erroneous import statements and delete them.
+
+### When You Sync ###
+
+Every time you repo sync, or otherwise change files outside of Eclipse (especially the .classpath), you need to refresh Eclipse's view of things:
+
+1. Window > Show View > Navigator
+
+1. In the Navigator, right-click on the project name
+
+1. Click Refresh in the context menu
+
+### Adding Apps to the Build Path ###
+
+The default `.classpath` includes the source to the core system and a sample set of apps, but might not include the particular app you may want to work on. To add an app, you must add the app's source directory. To do this inside Eclipse:
+
+1. Project > Properties
+
+1. Select "Java Build Path" from the left-hand menu.
+
+1. Choose the "Source" tab.
+
+1. Click "Add Folder..."
+
+1. Add your app's `src` directory.
+
+1. Click OK.
+
+When you're done, the "source folder" path in the list should look like
+
+ android/packages/apps/YOURAPP/src
+
+Depending on which app(s) you include, you may also need to include `othersrc/main/java` directories under `android/dalvik/libcore`. Do this if you find you cannot build with the default set.
+
+## Eclipse formatting ##
+
+You can import files in `development/ide/eclipse` to make Eclipse
+follow the Android style rules.
+
+1. Select Window > Preferences > Java > Code Style.
+
+1. Use Formatter > Import to import `android-formatting.xml`.
+
+1. Organize Imports > Import to import `android.importorder`.
+
+## Debugging the emulator with Eclipse ##
+
+You can also use eclipse to debug the emulator and step through code. First, start the emulator running:
+
+ cd /path/to/android/root
+ . build/envsetup.sh
+ lunch 1
+ make
+ emulator
+
+If the emulator is running, you should see a picture of a phone.
+
+In another shell, start DDMS (the Dalvik debug manager):
+
+ cd /path/to/android/root
+ ddms
+
+You should see a splufty debugging console.
+
+Now, in eclipse, you can attach to the emulator:
+
+1. Run > Open Debug Dialog...
+
+1. Right-click "Remote Java Application", select "New".
+
+1. Pick a name, i.e. "android-debug" or anything you like.
+
+1. Set the "Project" to your project name.
+
+1. Keep the Host set to "localhost", but change Port to 8700.
+
+1. Click the "Debug" button and you should be all set.
+
+Note that port 8700 is attached to whatever process is currently selected in the DDMS console, so you need to sure that DDMS has selected the process you want to debug.
+
+You may need to open the Debug perspective (next to the "Java" perspective icon in the upper-right, click the small "Open Perspective" icon and select "Debug"). Once you do, you should see a list of threads; if you select one and break it (by clicking the "pause" icon), it should show the stack trace, source file, and line where execution is at. Breakpoints and whatnot should all work.
+
+## Bonus material ##
+
+Replace Ctrl with the Apple key on Mac.
+
+shortcut | function
+-------------|-----------------
+Ctrl-Shift-o | Organize imports
+Ctrl-Shift-t | load class by name
+Ctrl-Shift-r | load non-class resource by name
+Ctrl-1 | quick fix
+Ctrl-e | Recently viewed files
+Ctrl-space | auto complete
+Shift-Alt-r | refactor:rename
+Shift-Alt-v | refactor:move
+
+## Eclipse is not working correctly, what should I do? ##
+
+Make sure:
+
+- You followed the instructions on this page precisely.
+
+- Your Problems view doesn't show any errors.
+
+- Your application respects the package/directory structure.
+
+If you're still having problems, please contact one of the Android mailing lists or IRC channels.
+
diff --git a/src/source/using-repo.md b/src/source/using-repo.md
new file mode 100644
index 0000000..d7bcb92
--- /dev/null
+++ b/src/source/using-repo.md
@@ -0,0 +1,191 @@
+# Repo command reference #
+
+Repo usage takes the following form:
+
+ repo COMMAND OPTIONS
+
+Optional elements are shown in brackets [ ]. Once Repo is installed, you can get information about any command by running
+
+ repo help COMMAND
+
+Many commands take a project list as an argument. You can specify project-list as a list of names or a list of paths to local source directories for the projects:
+
+ repo sync [PROJECT0 PROJECT1 ... PROJECTN]
+ repo sync [/PATH/TO/PROJECT0 ... /PATH/TO/PROJECTN]
+
+[TOC]
+
+## init ##
+
+ $ repo init -u URL [OPTIONS]
+
+Installs Repo in the current directory. This creates a `.repo/` directory that contains Git repositories for the Repo source code and the standard Android manifest files. The `.repo/` directory also contains `manifest.xml`, which is a symlink to the selected manifest in the `.repo/manifests/` directory.
+
+Options:
+
+* `-u`: specify a URL from which to retrieve a manifest repository. The common manifest can be found at `git://android.git.kernel.org/platform/manifest.git`
+
+* `-m`: select a manifest file within the repository. If no manifest name is selected, the default is default.xml.
+
+* `-b`: specify a revision, i.e., a particular manifest-branch.
+
+*Note: For all remaining Repo commands, the current working directory must either be the parent directory of `.repo/` or a subdirectory of the parent directory.*
+
+
+## sync ##
+
+ repo sync [PROJECT_LIST]
+
+Downloads new changes and updates the working files in your local environment. If you run `repo sync` without any arguments, it will synchronize the files for all the projects.
+
+When you run `repo sync`, this is what happens:
+
+- If the project has never been synchronized, then `repo sync` is equivalent to `git clone`. All branches in the remote repository are copied to the local project directory.
+
+- If the project has already been synchronized once, then `repo sync` is equivalent to:
+
+ git remote update
+ git rebase origin/BRANCH
+
+ where `BRANCH` is the currently checked-out branch in the local project directory. If the local branch is not tracking a branch in the remote repository, then no synchronization will occur for the project.
+
+- If the git rebase operation results in merge conflicts, you will need to use the normal Git commands (for example, `git rebase --continue`) to resolve the conflicts.
+
+After a successful `repo sync`, the code in specified projects will be up to date with the code in the remote repository.
+
+Options:
+
+* `-d`: switch specified projects back to the manifest revision. Helpful if the project is currently on a topic branch, but the manifest revision is temporarily needed.
+
+* `-s`: sync to a known good build as specified by the manifest-server element in the current manifest.
+
+* `-f`: proceed with syncing other projects even if a project fails to sync.
+
+
+## upload ##
+
+ repo upload [PROJECT_LIST]
+
+For the specified projects, Repo compares the local branches to the remote branches updated during the last repo sync. Repo will prompt you to select one or more of the branches that have not yet been uploaded for review.
+
+After you select one or more branches, all commits on the selected branches are transmitted to Gerrit over an SSH connection.You will need to configure an SSH key to enable upload authorization. Visit [SSH Keys](http://review.source.android.com/Gerrit#settings,ssh-keys) within the user settings panel to register your public keys with Gerrit. To enable password-less uploads, consider using ssh-agent on your client system.
+
+When Gerrit receives the object data over its SSH server, it will turn each commit into a change so that reviewers can comment on each commit individually. To combine several "checkpoint" commits together into a single commit, use git rebase -i before you run repo upload.
+
+If you run repo upload without any arguments, it will search all the projects for changes to upload.
+
+To make edits to changes after they have been uploaded, you should use a tool like `git rebase -i` or `git commit --amend` to update your local commits. After your edits are complete:
+
+- Make sure the updated branch is the currently checked out branch.
+
+- Use `repo upload --replace PROJECT` to open the change matching editor.
+
+- For each commit in the series, enter the Gerrit change ID inside the brackets:
+
+ # Replacing from branch foo
+ [ 3021 ] 35f2596c Refactor part of GetUploadableBranches to lookup one specific...
+ [ 2829 ] ec18b4ba Update proto client to support patch set replacments
+ [ 3022 ] c99883fe Teach 'repo upload --replace' how to add replacement patch se...
+ # Insert change numbers in the brackets to add a new patch set.
+ # To create a new change record, leave the brackets empty.
+
+After the upload is complete the changes will have an additional Patch Set.
+
+
+## diff ##
+
+ repo diff [PROJECT_LIST]
+
+Shows outstanding changes between commit and working tree using `git diff`.
+
+
+## download ##
+
+ repo download TARGET CHANGE
+
+Downloads the specified change from the review system and makes it available in your project's local working directory.
+
+For example, to download [change 1241](http://review.source.android.com/1241) into your platform/frameworks/base directory:
+
+ $ repo download platform/frameworks/base 1241
+
+A `repo sync` should effectively remove any commits retrieved via `repo download`. Or, you can check out the remote branch; e.g., `git checkout m/master`.
+
+*Note: There is a slight mirroring lag between when a change is visible on the web in [Gerrit](http://review.source.android.com) and when `repo download` will be able to find it, because changes are actually downloaded off the git://android.git.kernel.org/ mirror farm. Hence there will always be a lag of approximately 5 minutes before Gerrit pushes newly uploaded changes out to the mirror farm.*
+
+
+## forall ##
+
+ repo forall [PROJECT_LIST] -c COMMAND
+
+Executes the given shell command in each project. The following additional environment variables are made available by `repo forall`:
+
+* `REPO_PROJECT` is set to the unique name of the project.
+
+* `REPO_PATH` is the path relative to the root of the client.
+
+* `REPO_REMOTE` is the name of the remote sstem from the manifest.
+
+* `REPO_LREV` is the name of the revision from the manifest, translated to a local tracking branch. Used if you need to pass the manifest revision to a locally executed git command.
+
+* `REPO_RREV` is the name of the revision from the manifest, exactly as written in the manifest.
+
+Options:
+
+* `-c`: command and arguments to execute. The command is evaluated through `/bin/sh` and any arguments after it are passed through as shell positional parameters.
+
+* `-p`: show project headers before output of the specified command. This is achieved by binding pipes to the command's stdin, stdout, and sterr streams, and piping all output into a continuous stream that is displayed in a single pager session.
+
+* `-v`: show messages the command writes to stderr.
+
+
+## prune ##
+
+ repo prune [PROJECT_LIST]
+
+Prunes (deletes) topics that are already merged.
+
+
+## start ##
+
+ repo start BRANCH_NAME [PROJECT_LIST]
+
+Begins a new branch for development, starting from the revision specified in the manifest.
+
+The `BRANCH_NAME` argument should provide a short description of the change you are trying to make to the projects.If you don't know, consider using the name default.
+
+The `PROJECT_LIST` specifies which projects will participate in this topic branch.
+
+*Note: "." is a useful shorthand for the project in the current working directory.*
+
+
+## status ##
+
+ repo status [PROJECT_LIST]
+
+Compares the working tree to the staging area (index) and the most recent commit on this branch (HEAD) in each project specified. Displays a summary line for each file where there is a difference between these three states.
+
+To see the status for only the current branch, run `repo status`. The status information will be listed by project. For each file in the project, a two-letter code is used:
+
+In the first column, an uppercase letter indicates how the staging area differs from the last committed state.
+
+letter | meaning | description
+-------|----------------|-------------------------
+- | no change | same in HEAD and index
+A | added | not in HEAD, in index
+M | modified | in HEAD, modified in index
+D | deleted | in HEAD, not in index
+R | renamed | not in HEAD, path changed in index
+C | copied | not in HEAD, copied from another in index
+T | mode changed | same content in HEAD and index, mode changed
+U | unmerged | conflict between HEAD and index; resolution required
+
+In the second column, a lowercase letter indicates how the working directory differs from the index.
+
+letter | meaning | description
+-------|----------------|----------------------------
+- | new/unknown | not in index, in work tree
+m | modified | in index, in work tree, modified
+d | deleted | in index, not in work tree
+
+
diff --git a/src/source/version-control.md b/src/source/version-control.md
new file mode 100644
index 0000000..5a4a2a4
--- /dev/null
+++ b/src/source/version-control.md
@@ -0,0 +1,162 @@
+# Version Control with Repo and Git #
+
+To work with the Android code, you will need to use both Git and Repo. In most situations, you can use Git instead of Repo, or mix Repo and Git commands to form complex commands. Using Repo for basic across-network operations will make your work much simpler, however.
+
+**Git** is an open-source version-control system designed to handle very large projects that are distributed over multiple repositories. In the context of Android, we use Git for local operations such as local branching, commits, diffs, and edits. One of the challenges in setting up the Android project was figuring out how to best support the outside community--from the hobbiest community to large OEMs building mass-market consumer devices. We wanted components to be replaceable, and we wanted interesting components to be able to grow a life of their own outside of Android. We first chose a distributed revision control system, then further narrowed it down to Git.
+
+**Repo** is a repository management tool that we built on top of Git. Repo unifies the many Git repositories when necessary, does the uploads to our [revision control system](http://review.source.android.com/), and automates parts of the Android development workflow. Repo is not meant to replace Git, only to make it easier to work with Git in the context of Android. The repo command is an executable Python script that you can put anywhere in your path. In working with the Android source files, you will use Repo for across-network operations. For example, with a single Repo command you can download files from multiple repositories into your local working directory.
+
+**Gerrit** is a web-based code review system for projects that use git. Gerrit encourages more centralized use of Git by allowing all authorized users to submit changes, which are automatically merged if they pass code review. In addition, Gerrit makes reviewing easier by displaying changes side by side in-browser and enabling inline comments.
+
+## Basic Workflow ##
+
+<div style="float:right">
+ <img src="/images/submit-patches-0.png">
+</div>
+
+The basic pattern of interacting with the repositories is as follows:
+
+1. Use `repo start` to start a new topic branch.
+
+1. Edit the files.
+
+1. Use `git add` to stage changes.
+
+1. Use `git commit` to commit changes.
+
+1. Use `repo upload` to upload changes to the review server.
+
+# Task reference #
+
+The task list below shows a summary of how to do common Repo and Git tasks.
+For complete quick-start information and examples, see [Getting started](downloading.html).
+
+## Synchronizing your client ##
+
+To synchronize the files for all available projects:
+
+ $ repo sync
+
+To synchronize the files for selected projects:
+
+ $ repo sync PROJECT0 PROJECT1 PROJECT2 ...
+
+## Creating topic branches ##
+
+Start a topic branch in your local work environment whenever you begin a change, for example when you begin work on a bug or new feature. A topic branch is not a copy of the original files; it is a pointer to a particular commit. This makes creating local branches and switching among them a light-weight operation. By using branches, you can isolate one aspect of your work from the others. For an interesting article about using topic branches, see [Separating topic branches](http://www.kernel.org/pub/software/scm/git/docs/howto/separating-topic-branches.txt).
+<img src="/images/external-link.png">
+
+To start a topic branch using Repo:
+
+ $ repo start BRANCH_NAME
+
+To verify that your new branch was created:
+
+ $ repo status
+
+## Using topic branches ##
+
+To assign the branch to a particular project:
+
+ $ repo start BRANCH_NAME PROJECT
+
+To switch to another branch that you have created in your local work environment:
+
+ $ git checkout BRANCH_NAME
+
+To see a list of existing branches:
+
+ $ git branch
+
+or
+
+ $ repo branches
+
+The name of the current branch will be preceded by an asterisk.
+
+*Note: A bug might be causing `repo sync` to reset the local topic branch. If `git branch` shows \* (no branch) after you run `repo sync`, then run `git checkout` again.*
+
+## Staging files ##
+
+By default, Git notices but does not track the changes you make in a project. In order to tell git to preserve your changes, you must mark them for inclusion in a commit. This is also called "staging".
+
+You can stage your changes by running
+
+ git add
+
+which accepts as arguments any files or directories within the project directory. Despite the name, `git add` does not simply add files to the git repository; it can also be used to stage file modifications and deletions.
+
+## Viewing client status ##
+
+To list the state of your files:
+
+ $ repo status
+
+To see uncommitted edits:
+
+ $ repo diff
+
+The `repo diff` command shows every local edit that you have made that would *not* go into the commit, if you were to commit right now. To see every edit that would go into the commit if you were to commit right now, you need a Git command, `git diff`. Before running it, be sure you are in the project directory:
+
+ $ cd ~/WORKING_DIRECTORY/PROJECT
+ $ git diff --cached
+
+## Committing changes ##
+
+A commit is the basic unit of revision control in git, consisting of a snapshot of directory structure and file contents for the entire project. Creating a commit in git is as simple as typing
+
+ git commit
+
+You will be prompted for a commit message in your favorite editor; please provide a helpful message for any changes you submit to the AOSP. If you do not add a log message, the commit will be aborted.
+
+## Uploading changes to Gerrit ##
+
+Before uploading, update to the latest revisions:
+
+ repo sync
+
+Next run
+
+ repo upload
+
+This will list the changes you have committed and prompt you to select which branches to upload to the review server. If there is only one branch, you will see a simple `y/n` prompt.
+
+## Recovering sync conflicts ##
+
+If a `repo sync` shows sync conflicts:
+
+- View the files that are unmerged (status code = U).
+- Edit the conflict regions as necessary.
+- Change into the relevant project directory, run `git add` and `git commit` for the files in question, and then "rebase" the changes. For example:
+
+ $ git add .
+ $ git commit
+ $ git rebase --continue
+
+- When the rebase is complete start the entire sync again:
+
+ $ repo sync PROJECT0 PROJECT1 ... PROJECTN
+
+## Cleaning up your client files ##
+
+To update your local working directory after changes are merged in Gerrit:
+
+ $ repo sync
+
+To safely remove stale topic branches:
+
+ $ repo prune
+
+## Deleting a client ##
+
+Because all state information is stored in your client, you only need to delete the directory from your filesystem:
+
+ $ rm -rf WORKING_DIRECTORY
+
+Deleting a client will *permanently delete* any changes you have not yet uploaded for review.
+
+# Git and Repo cheatsheet #
+
+<img src="/images/git-repo-1.png">
+
+