diff --git a/scripts/build.py b/scripts/build.py
index 12bcb98..33a1e33 100755
--- a/scripts/build.py
+++ b/scripts/build.py
@@ -14,21 +14,15 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-import os
+import codecs
 import glob
+import markdown
+import os
 import shutil
 import string
 import subprocess
 
 
-# call markdown as a subprocess, and capture the output
-def markdown(raw_file):
-  extensions = '-x tables -x "toc(title=In This Document)" -x def_list'
-  command = 'markdown' + ' ' + extensions + ' ' + raw_file
-  p = subprocess.Popen(command, stdout = subprocess.PIPE, shell = True)
-  return p.communicate()[0]
-
-
 # read just the title (first heading) from a source page
 def get_title(raw_file):
   for line in open(raw_file, 'r'):
@@ -63,6 +57,11 @@
 category = 'home'
 parents = {}
 for curdir, subdirs, files in os.walk(SRC_DIR):
+  def md(path):
+    text = codecs.open(path, encoding='utf8').read()
+    extensions = ['tables', 'def_list', 'toc(title=In This Document)']
+    return markdown.markdown(text, extensions)
+
   print 'Processing %s...'  % (curdir,),
   # Step A: split path, and update cached category name if needed
   curdir = os.path.normpath(curdir)
@@ -86,19 +85,19 @@
     parent = ('', '', '')
 
   if 'sidebar.md' in files:
-    sidebar = markdown(os.path.join(curdir, 'sidebar.md'))
+    sidebar = md(os.path.join(curdir, 'sidebar.md'))
     del files[files.index('sidebar.md')]
   else:
     sidebar = parent[0]
 
   if 'sidebar2.md' in files:
-    sidebar2 = markdown(os.path.join(curdir, 'sidebar2.md'))
+    sidebar2 = md(os.path.join(curdir, 'sidebar2.md'))
     del files[files.index('sidebar2.md')]
   else:
     sidebar2 = parent[1]
 
   if 'sidebar3.md' in files:
-    sidebar3 = markdown(os.path.join(curdir, 'sidebar3.md'))
+    sidebar3 = md(os.path.join(curdir, 'sidebar3.md'))
     del files[files.index('sidebar3.md')]
   else:
     sidebar3 = parent[2]
@@ -112,15 +111,14 @@
     absfilename = os.path.join(curdir, f)
 
     if f.endswith('.md'):
-      main = markdown(absfilename)
+      main = md(absfilename)
       final = template.safe_substitute(main=main, sidebar=sidebar, sidebar2=sidebar2, \
           sidebar3=sidebar3, category=category, title=get_title(absfilename))
 
-      html = file(os.path.join(outdir, f.replace('.md', '.html')), 'w')
+      html = codecs.open(os.path.join(outdir, f.replace('.md', '.html')), 'w', encoding="utf8")
       html.write(final)
     else:
       shutil.copy(absfilename, os.path.join(outdir, f))
   print
 
 print 'Done.'
-
diff --git a/src/compatibility/4.0/versions.md b/src/compatibility/4.0/versions.md
index 1b70297..895b820 100644
--- a/src/compatibility/4.0/versions.md
+++ b/src/compatibility/4.0/versions.md
@@ -34,3 +34,5 @@
 - 4.0.1
 
 - 4.0.3
+
+- 4.0.4
diff --git a/src/compatibility/downloads.md b/src/compatibility/downloads.md
index 7072e65..fb7c7a8 100644
--- a/src/compatibility/downloads.md
+++ b/src/compatibility/downloads.md
@@ -26,8 +26,8 @@
 Android 4.0.3 is found in the 'android-4.0.3_r1' branch in the open-source tree.
 
 - [Android 4.0 Compatibility Definition Document (CDD)](4.0/android-4.0-cdd.pdf)
-- [Android 4.0.3 R2 Compatibility Test Suite (CTS)](https://dl.google.com/dl/android/cts/android-cts-4.0.3_r2-linux_x86-arm.zip)
-- [Android 4.0.3 R1 CTS Verifier](https://dl.google.com/dl/android/cts/android-cts-verifier-4.0.3_r1-linux_x86-arm.zip)
+- [Android 4.0.3 R3 Compatibility Test Suite (CTS)](https://dl.google.com/dl/android/cts/android-cts-4.0.3_r3-linux_x86-arm.zip)
+- [Android 4.0.3 R2 CTS Verifier](https://dl.google.com/dl/android/cts/android-cts-verifier-4.0.3_r2-linux_x86-arm.zip)
 
 ## Android 2.3 ##
 
@@ -36,8 +36,8 @@
 the open-source tree.
 
 - [Android 2.3 Compatibility Definition Document (CDD)](2.3/android-2.3.3-cdd.pdf)
-- [Android 2.3 R12 Compatibility Test Suite (CTS)](https://dl.google.com/dl/android/cts/android-cts-2.3_r12-linux_x86-arm.zip)
-- [Android 2.3 R2 CTS Verifier](https://dl.google.com/dl/android/cts/android-cts-verifier-2.3_r2-linux_x86-armv5.zip)
+- [Android 2.3 R13 Compatibility Test Suite (CTS)](https://dl.google.com/dl/android/cts/android-cts-2.3_r13-linux_x86-arm.zip)
+- [Android 2.3 R3 CTS Verifier](https://dl.google.com/dl/android/cts/android-cts-verifier-2.3_r3-linux_x86-armv5.zip)
 
 ## Android 2.2 ##
 
diff --git a/src/index.md b/src/index.md
index 54319bf..0ebaad9 100644
--- a/src/index.md
+++ b/src/index.md
@@ -28,14 +28,12 @@
 and researchers to develop custom builds. For information on how to obtain the
 software, visit our [Getting the Source](source/downloading.html) page.
 
-### Compatibility Definition for Android 2.3 ###
+### Compatibility Definition for Android 4.0 ###
 
-The Compatibility Definition Document for Android 2.3.3 has been published. 
-Android 2.3 allows device manufacturers to use the Android source code to ship
-a significantly wider variety of devices, including devices with extra-large
-screens, such as tablets. Android 2.3.3 adds enhanced Near-Field
-Communications support to the Android APIs. For more information, visit the 
-[Compatibility](compatibility/index.html) page.
+The Compatibility Definition Document for Android 4.0 has been published. 
+Android 4.0 allows device manufacturers to use the Android source code to ship
+a significantly wider variety of devices including phones and tablets. 
+For more information, visit the [Compatibility](compatibility/index.html) page.
 
 </div>
 
diff --git a/src/source/build-numbers.md b/src/source/build-numbers.md
index 07011aa..06a9559 100644
--- a/src/source/build-numbers.md
+++ b/src/source/build-numbers.md
@@ -111,7 +111,10 @@
 IML74K | android-4.0.3_r1   | Nexus S
 IML77  | android-4.0.3_r1.1 |
 IMM76  | android-4.0.4_r1   |
-IMM76D | android-4.0.4_r1.1 | Nexus S, Nexus S 4G, Galaxy Nexus, latest IceCreamSandwich version
+IMM76D | android-4.0.4_r1.1 | Nexus S, Nexus S 4G, Galaxy Nexus
+IMM76I | android-4.0.4_r1.2 | Galaxy Nexus
+IMM76K | android-4.0.4_r2   | Galaxy Nexus
+IMM76L | android-4.0.4_r2.1 | latest IceCreamSandwich version
 
 The branches froyo, gingerbread, ics-mr0, ics-mr1, represent development
 branches that do not exactly match configurations that were tested
diff --git a/src/source/building-devices.md b/src/source/building-devices.md
index bbc0962..1de1e61 100644
--- a/src/source/building-devices.md
+++ b/src/source/building-devices.md
@@ -145,10 +145,10 @@
 
 Device   | Branch                       | Build configuration
 ---------|------------------------------|------------------------
-maguro   | android-4.0.4_r1.1 or master | full_maguro-userdebug
+maguro   | android-4.0.4_r2.1 or master | full_maguro-userdebug
 panda    | master                       | full_panda-userdebug
-wingray  | android-4.0.4_r1.1 or master | full_wingray-userdebug
-crespo   | android-4.0.4_r1.1 or master | full_crespo-userdebug
+wingray  | android-4.0.4_r2.1 or master | full_wingray-userdebug
+crespo   | android-4.0.4_r2.1 or master | full_crespo-userdebug
 passion  | android-2.3.7_r1             | full_passion-userdebug
 sapphire | android-2.2.3_r1             | full_sapphire-userdebug
 dream    | android-2.2.3_r1             | full_dream-userdebug
@@ -204,6 +204,9 @@
 2.3.6 (GRK39F)  | I9020XXKA3           | I9020XXKF1      | All previous versions
 4.0.3 (IML74K)  | I9020XXKL1           | I9020XXKI1      | All previous versions
 4.0.4 (IMM76D)  | I9020XXKL1           | I9020XXKI1
+4.0.4 (IMM76I)  | I9020XXKL1           | I9020XXKI1
+4.0.4 (IMM76K)  | I9020XXKL1           | I9020XXKI1
+4.0.4 (IMM76L)  | I9020XXKL1           | I9020XXKI1
 
 Nexus S (850MHz version "UC", i9020a):
 
@@ -216,6 +219,9 @@
 2.3.6 (GRK39F)  | I9020XXKA3           | I9020UCKF1      | All previous versions
 4.0.3 (IML74K)  | I9020XXKL1           | I9020UCKF1      | All previous versions
 4.0.4 (IMM76D)  | I9020XXKL1           | I9020UCKJ1
+4.0.4 (IMM76I)  | I9020XXKL1           | I9020UCKJ1
+4.0.4 (IMM76K)  | I9020XXKL1           | I9020UCKJ1
+4.0.4 (IMM76L)  | I9020XXKL1           | I9020UCKJ1
 
 Nexus S (Korea version "KR", m200):
 
@@ -226,7 +232,10 @@
 2.3.5 (GRJ90)   | I9020XXKA3           | M200KRKC1       | All previous versions
 2.3.6 (GRK39F)  | I9020XXKA3           | M200KRKC1       | All previous versions
 4.0.3 (IML74K)  | I9020XXKL1           | M200KRKC1       | All previous versions
-4.0.4 (IMM76D)  | I9020XXKL1           | M200KRKC1       | Versions from 2.3.6
+4.0.4 (IMM76D)  | I9020XXKL1           | M200KRKC1
+4.0.4 (IMM76I)  | I9020XXKL1           | M200KRKC1
+4.0.4 (IMM76K)  | I9020XXKL1           | M200KRKC1
+4.0.4 (IMM76L)  | I9020XXKL1           | M200KRKC1
 
 Galaxy Nexus (GSM/HSPA+):
 
@@ -235,7 +244,10 @@
 4.0.1 (ITL41D)  | PRIMEKJ10            | I9250XXKK1
 4.0.2 (ICL53F)  | PRIMEKK15            | I9250XXKK6      | All previous versions
 4.0.3 (IML74K)  | PRIMEKL01            | I9250XXKK6      | All previous versions
-4.0.4 (IMM76D)  | PRIMEKL03            | I9250XXLA02
+4.0.4 (IMM76D)  | PRIMELA03            | I9250XXLA02
+4.0.4 (IMM76I)  | PRIMELA03            | I9250XXLA02
+4.0.4 (IMM76K)  | PRIMELA03            | I9250XXLA02
+4.0.4 (IMM76L)  | PRIMELA03            | I9250XXLA02
 
 If you're building a new version of Android, if your Nexus S or
 Galaxy Nexus has
diff --git a/src/source/building-kernels.md b/src/source/building-kernels.md
index 8eb9639..144a2f4 100644
--- a/src/source/building-kernels.md
+++ b/src/source/building-kernels.md
@@ -45,12 +45,25 @@
 Depending on which kernel you want,
 
     $ git clone https://android.googlesource.com/kernel/common.git
+    $ git clone https://android.googlesource.com/kernel/exynos.git
     $ git clone https://android.googlesource.com/kernel/goldfish.git
     $ git clone https://android.googlesource.com/kernel/msm.git
     $ git clone https://android.googlesource.com/kernel/omap.git
     $ git clone https://android.googlesource.com/kernel/samsung.git
     $ git clone https://android.googlesource.com/kernel/tegra.git
 
+  - The `goldfish` project contains the kernel sources for the emulated
+platforms.
+  - The `msm` project has the sources for ADP1, ADP2, Nexus One, and
+can be used as a starting point for work on Qualcomm MSM chipsets.
+  - The `omap` project is used for PandaBoard and Galaxy Nexus, and
+can be used as a starting point for work on TI OMAP chipsets.
+  - The `samsung` project is used for Nexus S and can be used as a
+starting point for work on Samsung Hummingbird chipsets.
+  - The `tegra` project is for Xoom, and can be used as a starting
+point for work on NVIDIA Tegra chipsets.
+  - The `exynos` project can be used as a starting point for work
+on Samsung Exynos chipsets.
 
 ## Downloading a prebuilt gcc ##
 
@@ -75,6 +88,10 @@
 To build the tuna kernel, you may run the previous commands replacing all
 instances of "panda" with "tuna".
 
-The image is output as arch/arm/boot/zImage.  You may copy it as
-device/<vendor>/<name>/kernel or device/ti/panda/kernel in the case of this
+  - The kernel for maguro and toro is `device/samsung/tuna/kernel`
+  - The kernel for crespo and crespo4g is `device/samsung/crespo/kernel`
+  - The kernel for stingray and wingray is `device/moto/wingray/kernel`
+
+The image is output as `arch/arm/boot/zImage`.  You may copy it as
+`device/<vendor>/<name>/kernel` or `device/ti/panda/kernel` in the case of this
 example.
diff --git a/src/source/building.md b/src/source/building.md
index 1cd13c9..a9837e2 100644
--- a/src/source/building.md
+++ b/src/source/building.md
@@ -145,14 +145,6 @@
 
     $ 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
diff --git a/src/source/downloading.md b/src/source/downloading.md
index d76e86c..7fabab5 100644
--- a/src/source/downloading.md
+++ b/src/source/downloading.md
@@ -32,11 +32,8 @@
         $ curl https://dl-ssl.google.com/dl/googlesource/git-repo/repo > ~/bin/repo
         $ chmod a+x ~/bin/repo
 
- - For version 1.15, the SHA-1 checksum for repo is
- 8eb56d98b36d615c3efec51868e87bebe757feb1
-
- - For version 1.16, the SHA-1 checksum for repo is
- f3bfa7fd2d0a44aa40579bb0242cc20df37b5e17
+ - For version 1.17, the SHA-1 checksum for repo is
+ ddd79b6d5a7807e911b524cb223bc3544b661c28
 
 
 ## Initializing a Repo client ##
diff --git a/src/source/initializing.md b/src/source/initializing.md
index 8893929..2967158 100644
--- a/src/source/initializing.md
+++ b/src/source/initializing.md
@@ -24,15 +24,31 @@
 
 For an overview of the entire code-review and code-update process, see [Life of a Patch](life-of-a-patch.html).
 
+# Choosing a Branch #
 
+Some of the requirements for your build environment are determined by which
+version of the source code you plan to compile. See
+[Build Numbers](build-numbers.html) for a full listing of branches you may
+choose from. You may also choose to download and build the latest source code
+(called "master"), in which case you will simply omit the branch specification
+when you initialize the repository.
+
+Once you have selected a branch, follow the appropriate instructions below to
+set up your build environment.
 
 # Setting up a Linux build environment #
 
+These instructions apply to all branches, including master.
+
 The Android build is routinely tested in house on recent versions of
 Ubuntu LTS (10.04), but most distributions should have the required
 build tools available. Reports of successes or failures on other
 distributions are welcome.
 
+For Gingerbread (2.3.x) and newer versions, including the master
+branch, a 64-bit environment is required. Older versions can be
+compiled on 32-bit systems.
+
 *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 16GB of RAM/swap and 30GB or more of disk space in order to
@@ -97,9 +113,10 @@
 
     $ sudo apt-get install git-core gnupg flex bison gperf build-essential \
       zip curl libc6-dev libncurses5-dev:i386 x11proto-core-dev \
-      libx11-dev:i386 libreadline6-dev:i386 libgl1-mesa-dev:i386 \
-      g++-multilib mingw32 openjdk-6-jdk tofrodos python-markdown \
-      libxml2-utils xsltproc zlib1g-dev:i386
+      libx11-dev:i386 libreadline6-dev:i386 libgl1-mesa-glx:i386 \
+      libgl1-mesa-dev g++-multilib mingw32 openjdk-6-jdk tofrodos \
+      python-markdown libxml2-utils xsltproc zlib1g-dev:i386
+    $ sudo ln -s /usr/lib/i386-linux-gnu/mesa/libGL.so.1 /usr/lib/i386-linux-gnu/libGL.so
 
 ## Configuring USB Access ##
 
@@ -109,7 +126,7 @@
 
 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
+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.
 
@@ -134,6 +151,8 @@
     # fastboot protocol on panda (PandaBoard)
     SUBSYSTEM=="usb", ATTR{idVendor}=="0451", ATTR{idProduct}=="d022", MODE="0600", OWNER="<username>"
     # usbboot protocol on panda (PandaBoard)
+    SUBSYSTEM=="usb", ATTR{idVendor}=="0451", ATTR{idProduct}=="d00f", MODE="0600", OWNER="<username>"
+    # usbboot protocol on panda (PandaBoard ES)
     SUBSYSTEM=="usb", ATTR{idVendor}=="0451", ATTR{idProduct}=="d010", MODE="0600", OWNER="<username>"
 
 Those new rules take effect the next time a device is plugged in.
@@ -170,18 +189,56 @@
 
 This setting is stored in the CCACHE_DIR and is persistent.
 
+## Using a separate output directory ##
+
+By default, the output of each build is stored in the out/
+subdirectory of the matching source tree.
+
+On some machines with multiple storage devices, builds are
+faster when storing the source files and the output on
+separate volumes. For additional performance, the output
+can be stored on a filesystem optimized for speed instead
+of crash robustness, since all files can be re-generated
+in case of filesystem corruption.
+
+To set this up, export the `OUT_DIR_COMMON_BASE` variable
+to point to the location where your output directories
+will be stored.
+
+    export OUT_DIR_COMMON_BASE=<path-to-your-out-directory>
+
+The output directory for each separate source tree will be
+named after the directory holding the source tree.
+
+For instance, if you have source trees as `/source/master1`
+and `/source/master2` and `OUT_DIR_COMMON_BASE` is set to
+`/output`, the output directories will be `/output/master1`
+and `/output/master2`.
+
+It's important in that case to not have multiple source
+trees stored in directories that have the same name,
+as those would end up sharing an output directory, with
+unpredictable results.
+
+This is only supported on branches newer than 4.0.x
+(IceCreamSandwich).
 
 # 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.6 (Snow Leopard).
+In a default installation, OS X runs on a case-preserving but case-insensitive
+filesystem. This type of filesystem is not supported by git and will cause some
+git commands (such as "git status") to behave abnormally. Because of this, we
+recommend that you always work with the AOSP source files on a case-sensitive
+filesystem. This can be done fairly easily using a disk image, discussed below.
 
-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.
+Once the proper filesystem is available, building the master branch in a modern
+OS X environment is very straightforward. Earlier branches, including ICS,
+require some additional tools and SDKs.
 
-## Creating a case sensitive disk image ##
+### 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
+You can create a case-sensitive filesystem within your existing OS X environment
+using a disk image. To create the image, launch Disk
 Utility and select "New Image".  A size of 25GB is the minimum to
 complete the build, larger numbers are more future-proof. Using sparse images
 saves space while allowing to grow later as the need arises. Be sure to select
@@ -198,9 +255,25 @@
 
 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 ##
+## Master branch ##
 
-- Install XCode from [the Apple developer site](http://developer.apple.com/).
+To build the latest source in a Mac OS environment, you will need an Intel/x86
+machine running MacOS 10.6 (Snow Leopard) or MacOS 10.7 (Lion), along with Xcode
+4.2 (Apple's Developer Tools). Although Lion does not come with a JDK, it should
+install automatically when you attempt to build the source.
+
+The remaining sections for Mac OS X only apply to those who wish to build
+earlier branches.
+
+## Branch 4.0.x and all earlier branches ##
+
+To build android-4.0.x and earlier branches in a Mac OS environment, you need an
+Intel/x86 machine running MacOS 10.5 (Leopard) or MacOS 10.6 (Snow Leopard). You
+will need the MacOS 10.5 SDK.
+
+### Installing required packages ###
+
+- Install Xcode from [the Apple developer site](http://developer.apple.com/).
 We recommend version 3.1.4 or newer, i.e. gcc 4.2.
 Version 4.x could cause difficulties.
 If you are not already registered as an Apple developer, you will have to
@@ -222,7 +295,7 @@
 
         $ POSIXLY_CORRECT=1 sudo port install bison
 
-## Reverting from make 3.82 ##
+### Reverting from make 3.82 ###
 
 For versions of Android before ICS, 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:
 
@@ -246,7 +319,7 @@
 
         $ sudo port install gmake @3.81
 
-## Setting a file descriptor limit ##
+### 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.  
 
diff --git a/src/source/known-issues.md b/src/source/known-issues.md
index 4fa1bea..74579de 100644
--- a/src/source/known-issues.md
+++ b/src/source/known-issues.md
@@ -194,3 +194,43 @@
 
 **Fix**: Build Android in an environment that has as few
 customizations as possible.
+
+## Build error with 4.0.x and earlier on MacOS 10.7. ##
+
+**Symptom**: Building IceCreamSandwich 4.0.x (and older
+versions) fails on MacOS 10.7 with errors similar to this:
+`Undefined symbols for architecture i386: "_SDL_Init"`
+
+**Cause**: 4.0.x is not compatible with MacOS 10.7.
+
+**Fix**: Either downgrade to MacOS 10.6, or use the master
+branch, which can be built on MacOS 10.7.
+
+    $ repo init -b master
+    $ repo sync
+
+## Build error on MacOS with XCode 4.3. ##
+
+**Symptom**: All builds fail when using XCode 4.3.
+
+**Cause**: XCode 4.3 switched the default compiler from
+gcc to llvm, and llvm rejects code that used to be
+accepted by gcc.
+
+**Fix**: Use XCode 4.2.
+
+## Build error with 4.0.x and earlier on Ubuntu 11.10. ##
+
+**Symptom**: Building IceCreamSandwich 4.0.x (and older
+versions) on Ubuntu 11.10 and newer fails with errors similar to this:
+`<command-line>:0:0: warning: "_FORTIFY_SOURCE" redefined [enabled by default]`
+
+**Cause**: Ubuntu 11.10 uses a version of gcc where that symbol
+is defined by default, and Android also defines that symbol,
+which causes a conflict.
+
+**Fix**: Either downgrade to Ubuntu 10.04, or use the master
+branch, which can be compiled on Ubuntu 11.10 and newer.
+
+    $ repo init -b master
+    $ repo sync
diff --git a/src/source/submit-patches.md b/src/source/submit-patches.md
index 72531c3..0ea530d 100644
--- a/src/source/submit-patches.md
+++ b/src/source/submit-patches.md
@@ -38,6 +38,18 @@
 
 # For contributors #
 
+## Authenticate with the server ##
+
+Before you can upload to Gerrit, you need to establish a password that
+will identify you with the server. You only need to do this once.
+
+- Sign in on the [AOSP Gerrit Server](https://android-review.googlesource.com/).
+
+- Go to Settings -> HTTP Password -> Obtain Password
+
+- Follow the instructions on the subsquent pages, and copy-paste your
+password in `~/.netrc`. If there are two password lines, copy both.
+
 ## Start a repo branch ##
 
 For each change you intend to make, start a new branch within the relevant git repository:
diff --git a/src/source/using-repo.md b/src/source/using-repo.md
index b3bf9bb..b62f693 100644
--- a/src/source/using-repo.md
+++ b/src/source/using-repo.md
@@ -39,7 +39,7 @@
 
 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`
+* `-u`: specify a URL from which to retrieve a manifest repository. The common manifest can be found at `https://android.googlesource.com/platform/manifest`
 
 * `-m`: select a manifest file within the repository. If no manifest name is selected, the default is default.xml. 
 
diff --git a/src/tech/input/input-device-configuration-files.md b/src/tech/input/input-device-configuration-files.md
index 0a477d0..be6900a 100644
--- a/src/tech/input/input-device-configuration-files.md
+++ b/src/tech/input/input-device-configuration-files.md
@@ -62,7 +62,7 @@
 *   `/data/system/devices/idc/DEVICE_NAME.idc`
 
 When constructing a file path that contains the device name, all characters
-in the device name other than '0'-'9', 'a'-'z', 'A'-'Z', '-' or '_' are replaced by '_'.
+in the device name other than '0'-'9', 'a'-'z', 'A'-'Z', '-' or '\_' are replaced by '\_'.
 
 ## Syntax ##
 
diff --git a/src/tech/test_infra/index.md b/src/tech/test_infra/index.md
new file mode 100644
index 0000000..39ed155
--- /dev/null
+++ b/src/tech/test_infra/index.md
@@ -0,0 +1,20 @@
+<!--
+   Copyright 2012 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.
+-->
+
+# Test Infrastructure Technical Information #
+
+We make tests go vroom.
+
diff --git a/src/tech/test_infra/sidebar2.md b/src/tech/test_infra/sidebar2.md
new file mode 100644
index 0000000..1ddf988
--- /dev/null
+++ b/src/tech/test_infra/sidebar2.md
@@ -0,0 +1,5 @@
+# Infrastructure Components #
+
+- [Trade Federation](/tech/test_infra/tradefed/index.html)
+- [Notifilter](/tech/test_infra/notifilter.html)
+
diff --git a/src/tech/test_infra/tradefed/commandfile_format.md b/src/tech/test_infra/tradefed/commandfile_format.md
new file mode 100644
index 0000000..88c0a74
--- /dev/null
+++ b/src/tech/test_infra/tradefed/commandfile_format.md
@@ -0,0 +1,133 @@
+<!--
+   Copyright 2012 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.
+-->
+
+# Command File Format
+
+A command file allows one to specify sets of TF commands (that is, configurations with their
+associated arguments) to be specified all at once.  Further, the format used in the command file
+supports simple macro expansions, which makes it very useful without being unwieldy.  You can see a
+relatively involved example at the bottom of the page, as well as more gradual documentation
+immediately below.
+
+
+## Lines
+
+The format is line-based.
+
+* Each output line will be considered as the arguments for a single Configuration for Trade
+    Federation to run.
+* Each input line will turn into one or more output lines.
+
+In essence, the command file format combinatorially creates a sequence of Configuration specifications that it passes to Trade Federation to run.  Blank lines are ignored.  Comments are delimited by the "#" character and may only be preceded by whitespace.
+
+
+## Macros
+
+The specific syntax for defining a macro is discussed below in the Short Macro and Long Macro sections.  The following rules apply to all macros
+
+* The name of a macro must begin with an alpha character.  Each subsequent character may be any
+    alphanumeric, an underscore, or a hyphen.
+* A macro with name "macro_name" is invoked by adding macro_name() as an argument on some subsequent
+    line.
+* The macro format does not support passing arguments to macros.  It allows only concatenation.
+* A macro's expansion may contain invocations of other macros.  Technically, a macro's expansion may
+    contain invocations of itself, but in that case, the macro will never fully expand.
+* The parser currently has a hard limit of 10 iterations of expansion.  This will be made
+    configurable at some point.
+* During a single iteration of expansion:
+    * All short macro invocations on a line will be expanded a single level — macro invocations
+        embedded within the first-level expansions will not be expanded yet
+    * Only one long macro invocation on a line will be expanded.  This will be the left-most long
+        macro invocation.
+
+
+## Short Macros
+
+A short macro can be defined with the syntax:
+
+    MACRO macro_name = this is the macro expansion
+
+The macro expansion terminates at the end of the line.  For multi-line expansion, see Long Macros
+below.
+
+### Short Macro Expansion
+
+* `a macro_name() invocation`<br />
+  will be replaced by<br />
+  `a this is the macro expansion invocation`
+* `three macro_name() A macro_name() B macro_name()`<br />
+  will be replaced by (all during the first iteration)<br />
+  `three this is the macro expansion A this is the macro expansion B this is the macro expansion`
+
+
+## Long Macros
+
+A long macro can be defined with the syntax:
+
+    LONG MACRO macro_name
+      expansion line 1
+      expansion line 2
+      expansion line 3
+    END MACRO
+
+The macro is then invoked with th enormal `macro_name()` syntax.  Leading whitespace/indentation
+will be ignored.
+
+### Long Macro Expansion
+
+The output of a single input line will include one line for each combination of macro expansions on
+that line.  That is, the number of output lines is multiplicatively related to the number of macro
+expansions on that line:
+
+* Only a single long macro invocation per line will be expanded during a single iteration.  This
+    means that a line may only contain 10 long macro invocations to stay under the iteration count
+    limit.
+* A single invocation of a long macro on a single line will cause that line to expand to the number
+    of lines of the long macro's expansion.  On each expanded line, the invocation will be replaced
+    by the corresponding line of the macro's expansion.
+
+* Example 1:
+
+        a macro_name() invocation
+
+    will be replaced by (in a single iteration)
+
+        a expansion line 1 invocation
+        a expansion line 2 invocation
+        a expansion line 3 invocation
+
+* Example 2:
+
+        alpha macro_name() beta macro_name()
+
+    will be replaced by (during the first iteration)
+
+        alpha expansion line 1 beta macro_name()
+        alpha expansion line 2 beta macro_name()
+        alpha expansion line 3 beta macro_name()
+
+    which will be replaced by (during the second iteration)
+
+        alpha expansion line 1 beta expansion line 1
+        alpha expansion line 1 beta expansion line 2
+        alpha expansion line 1 beta expansion line 3
+        alpha expansion line 2 beta expansion line 1
+        alpha expansion line 2 beta expansion line 2
+        alpha expansion line 2 beta expansion line 3
+        alpha expansion line 3 beta expansion line 1
+        alpha expansion line 3 beta expansion line 2
+        alpha expansion line 3 beta expansion line 3
+
diff --git a/src/tech/test_infra/tradefed/getting_started.md b/src/tech/test_infra/tradefed/getting_started.md
new file mode 100644
index 0000000..4735aa5
--- /dev/null
+++ b/src/tech/test_infra/tradefed/getting_started.md
@@ -0,0 +1,249 @@
+<!--
+   Copyright 2012 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.
+-->
+
+# Getting Started
+
+## Using the console
+
+TF is based around an interactive console.  You can fire up the console by going to the
+`tools/tradefederation/` directory and running
+
+    $ ./tradefed.sh
+
+You should end up at a `tf >` prompt.
+
+The console is self-documenting.  Try entering "help"
+
+    tf >help
+    Enter 'q' or 'exit' to exit
+    Enter 'kill' to attempt to forcibly exit, by shutting down adb
+
+    Enter 'help list'  for help with 'list' commands
+    [...]
+
+As the help text suggests, the help menus are organized hierarchically
+
+    tf >help list
+    l(?:ist)? help:
+        i[nvocations]  List all invocation threads
+        d[evices]      List all detected or known devices
+    [...]
+
+The majority of commands have a convenient short form, which the help text displays.  The
+`l(?:ist)?` is a regular expression.  As an example, here are the four equivalent ways to list
+invocations:
+* `list invocations`
+* `list i`
+* `l invocations`
+* `l i`
+
+
+## Running a config/command
+
+This is documented by the `help run` command in the console.
+
+As a reminder, a command is a config along with all of its command-line arguments.  A command *must*
+begin with the name of the respective config.
+
+As a quick example, you could run the calculator unit tests like so:
+
+    $./tradefed.sh
+    tf >run instrument --package com.android.calculator2.tests
+
+As a shortcut, if you specify any arguments to `tradefed.sh`, it will attempt to execute them as if
+they were typed on the commandline.  So the short version of the above would be
+
+    $./tradefed.sh run instrument --package com.android.calculator2.tests
+
+In both of these cases, the name of the config is "instrument", and
+"--class com.android.calculator2.tests" is a command-line argument.  The command that is being run
+is "instrument --class com.android.calculator2.tests".
+
+TF can run both configs that are compiled in (such as the "instrument" config above), as well as
+configs that exist as xml files on the local filesystem.  You can see a list of compiled-in configs
+with the `list configs` console command.  Furthermore, you can investigate any config (compiled-in
+or local) by passing the "--help" or "--help-all" command-line arguments.  The "--help" argument
+will only show "important" arguments, and "--help-all" will show all arguments, regardless of
+whether they've been marked as "important" or not.  To take the final step, you can tell TF to print
+the contents of any config (compiled-in or local) with the `dump config <configname>` console
+command.
+
+### So, let's say you want to run the calculator instrumentation tests, but don't know where to start.
+
+You could try something like this sequence of steps.  First, look for a config that looks like it
+might do what you want:
+
+    tf >list configs
+    Use 'run command --help <configuration_name>' to get list of options for a configuration
+    Use 'dump config <configuration_name>' to display the configuration's XML content.
+
+    Available configurations include:
+    [...]
+      instrument: Runs a single Android instrumentation test on an existing device
+    [...]
+
+Now that you've found something reasonable-looking, see what options it takes.  The `list configs` output suggests trying `run command instrument --help`
+
+    tf >run command --help instrument
+    'instrument' configuration: Runs a single Android instrumentation test on an existing device
+
+    Printing help for only the important options. To see help for all options, use the --help-all flag
+    [...]
+      'instrumentation' test options:
+        -p, --package        The manifest package name of the Android test application to run.
+
+As the message suggests, if you need more options, use the "--help-all" flag instead of "--help".  In this case, we've got all we need.  You could figure out the package by checking with `runtest`, or reading testdefs.xml directly.  We use `runtest -n` to simply show what would be run without actually running it:
+
+    $runtest -n calculator
+    adb root
+    ONE_SHOT_MAKEFILE="packages/apps/Calculator/Android.mk" make -j4 -C "/srv/xsdg/master2" files
+    adb sync
+    adb  shell am instrument -w com.android.calculator2.tests/android.test.InstrumentationTestRunner
+
+The argument to `am instrument` that comes before the slash is the manifest package.  `android.test.InstrumentationTestRunner` is the default runner, so no need to set it if that's the
+right one.  Otherwise, using "--help-all" will tell you about the "--runner" argument, which you can
+use to specify an alternate runner.  Ok, so at this point, we've got the following command, which
+you'll recognize from above
+
+    tf >run instrument --package com.android.calculator2.tests
+
+
+## Interacting with a device
+
+### Generic device behavior in TF
+
+The running version of a command is called in `invocation`.  First and foremost, every invocation
+requires a device before it can run.  In addition to physical Android devices, TF can run tests with
+a mock device (by specifying the "-n" argument for the command), or with the Android emulator (by
+specifying the "-e" argument").
+
+The primary console command to figure out what devices are up to is `list devices`:
+
+    $./tradefed.sh
+    06-07 17:03:22 I/: Detected new device 016B756E03018007
+    06-07 17:03:22 I/: Detected new device 1700614743c14397
+    06-07 17:03:22 I/: Detected new device 3531C342606300EC
+    tf >l d
+    Serial            State      Product   Variant   Build   Battery
+    016B756E03018007  Available  tuna      toro      MASTER  100
+    1700614743c14397  Available  stingray  stingray  MASTER  100
+    3531C342606300EC  Available  herring   crespo4g  MASTER  92
+
+As far as the invocations are concerned, there are three device states: available, unavailable, and
+allocated.  An `Available` device is ready to be allocated for an invocation.  An `Unavailable`
+device is not ready for allocation, for any of a variety of reasons — TF may have deemed to the
+device as unstable, the device may be critically low on storage, or something else may be amiss.
+Finally, an `Allocated` device is a device that is already being used by an invocation.
+
+When you start TF, all detected physical devices will be checked for responsiveness with a simple
+shell command.  If the command completes successfully, the device will be listed as Available.  If
+the command fails, the device state will be shown as Unavailable.  Thereafter, a device will typically bounce between the Available and Allocated states as invocation requirements dictate.
+
+Finally, once invocations are already underway, you can see what's going on with the `list
+invocations` command
+
+    tf >run instrument --package com.android.calculator2.tests
+    06-07 17:18:31 I/TestInvocation: Starting invocation for 'stub' on build '0' on device 1700614743c14397
+    [...]
+    tf >l d
+    Serial            State      Product   Variant   Build   Battery
+    1700614743c14397  Allocated  stingray  stingray  MASTER  100
+    3531C342606300EC  Available  herring   crespo4g  JRN11   93
+    016B756E03018007  Available  tuna      toro      MASTER  100
+
+    tf >l i
+    Command Id  Exec Time  Device            State
+    1           0m:02      1700614743c14397  running stub on build 0
+
+
+### Running invocations on specific devices
+
+TF supports a number of filtering mechanisms for specifying which device or devices to use for a
+particular invocation.  Since the filtering mechanisms are run before a command turns into an
+invocation, you can find all of the filtering options in the help for any config:
+
+tf >run instrument --help-all
+[...]
+  device_requirements options:
+    -s, --serial         run this test on a specific device with given serial number(s).
+    --exclude-serial     run this test on any device except those with this serial number(s).
+    --product-type       run this test on device with this product type(s).  May also filter by variant using product:variant.
+    --property           run this test on device with this property value. Expected format <propertyname>=<propertyvalue>.
+    -e, --[no-]emulator  force this test to run on emulator. Default: false.
+    -d, --[no-]device    force this test to run on a physical device, not an emulator. Default: false.
+    --[no-]new-emulator  allocate a placeholder emulator. Should be used when config intends to launch an emulator Default: false.
+    -n, --[no-]null-device
+                         do not allocate a device for this test. Default: false.
+    --min-battery        only run this test on a device whose battery level is at least the given amount. Scale: 0-100
+    --max-battery        only run this test on a device whose battery level is strictly less than the given amount. Scale: 0-100
+[...]
+
+The built-in help should be pretty self-explanatory.  All of the filtering options excluding "-n",
+"-e", and "-d" may be specified as many times as needed.  So, for instance, to run an invocation
+using any Verizon Galaxy Nexus, you could do the following:
+
+    tf >run instrument --package com.android.calculator2.tests --product-type tuna:toro
+
+As another example, to run on a GSM device with a SIM, you could do the following:
+
+    tf >run instrument --package com.android.calculator2.tests --property gsm.sim.state=READY
+
+The filtering works by exclusion from the pool of Available devices, so the "--serial" option simply
+excludes devices that aren't in the list of required serials, and --exclude-serial excludes devices
+that *are* in its list.  As such, an argument like --exclude-serial XXX --serial XXX will simply
+make the respective command un-runnable — it will never match any device, since all devices are
+excluded.
+
+
+## Logging
+
+There are a few different aspects to logging in TF.  First and foremost, TF has a built-in logging
+infrastructure that's based on DDMLib's Log class.  For the common case, where the log tag is just
+the classname of the current class, you can use our CLog convenience shim.  In short, if you might
+have originally done this:
+
+    class ClassName {
+    private static final LOG_TAG = "ClassName";
+    [...]
+    Log.v(LOG_TAG, "This is a simple verbose log message");
+    Log.w(LOG_TAG, String.format("This warning message brought to you by the number %d", 17));
+
+You can now accomplish the same thing with the shim like this:
+
+    class ClassName {
+    [...]
+    CLog.v("This is a simple verbose log message");
+    CLog.w("This warning message brought to you by the number %d", 17);
+
+Each Invocation has its own ThreadGroup.  Any host-side logging that happens inside of that thread
+group is associated with the Invocation, and will be reported as that invocation's "host_log" after
+the Invocation completes.
+
+Device logging is performed as part of TradeFed's device wrapper.  We keep a buffer of up to 20 MB
+that captures log data as the device churns it out.  In particular, we are not limited by the size
+of the on-device logcat buffer.
+
+The next important piece is the ITestInvocationListener.  This is one of the components of an
+Invocation that handles results reporting.  Each reporter has the option to implement the #testLog
+method, which will be used to pass logfiles to that result reporter.  Among the files that are
+passed by TF itself will be the aforementioned host_log, as well as the device logcat for the device
+associated with the Invocation.
+
+<!--
+FIXME: discuss test result reporting, retrieving builds, doing things continuously, target prep and
+FIXME: flashing builds, extending tradefed (like CTS).
+-->
+
diff --git a/src/tech/test_infra/tradefed/index.md b/src/tech/test_infra/tradefed/index.md
new file mode 100644
index 0000000..ef7ab7f
--- /dev/null
+++ b/src/tech/test_infra/tradefed/index.md
@@ -0,0 +1,55 @@
+<!--
+   Copyright 2011 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.
+-->
+
+# Trade Federation Overview #
+
+TradeFederation (tradefed or TF for short) is a continuous test framework designed for running tests
+on Android devices. Its a Java application which runs on a host computer, and communicates to one or
+more Android devices using ddmlib (the library behind DDMS) over adb.
+
+## Features
+
+- modular, flexible design
+- has built in support for running many different types of Android tests: instrumentation, native/gtest, host-based JUnit, etc
+- provides reliability and recovery mechanism on top of adb
+- supports scheduling and running tests on multiple devices in parallel
+
+## Fundamentals
+The lifecycle of a test executed using TradeFederation is composed of four separate stages, designed
+around formally defined interfaces.
+
+- [Build provider](bp.html): Provides a build to test, downloading appropriate files if necessary
+- [Target preparer](tp.html): Prepares the test environment, e.g. software installation and setup
+- [Test](test.html): Executes test(s) and gathers test results
+- [Result reporter](result.html): Listens for test results, usually for the purpose of forwarding
+  test results to a repository
+
+The fundamental entity in TradeFederation is a Configuration. A Configuration is an XML file that
+declares the lifecycle components of a test.
+
+This separation of the test's lifecycle is intended to allow for reuse.  Using this design, you can
+create a Test, and then different Configurations to run it in different environments. For example,
+you could create a Configuration that will run a test on your local machine, and dump the result to
+stdout.  You could then create a second Configuration that would execute that same test, but use a
+different Result reporter to store the test results in a database.
+
+### Additional components of a configuration
+
+- [Device recovery](recovery.html): mechanism to recover device communication if lost
+- [Logger](logger.html): collects tradefed logging data
+
+A complete TradeFederation test execution, across its entire lifecycle, is referred to as an
+Invocation.
diff --git a/src/tech/test_infra/tradefed/sidebar3.md b/src/tech/test_infra/tradefed/sidebar3.md
new file mode 100644
index 0000000..2aa2b1d
--- /dev/null
+++ b/src/tech/test_infra/tradefed/sidebar3.md
@@ -0,0 +1,5 @@
+# Trade Federation Docs #
+
+- [Getting Started](getting_started.html)
+- [Tutorial](tutorial.html)
+- [Command Files](commandfile_format.html)
diff --git a/src/tech/test_infra/tradefed/tutorial.md b/src/tech/test_infra/tradefed/tutorial.md
new file mode 100644
index 0000000..e9b5e5f
--- /dev/null
+++ b/src/tech/test_infra/tradefed/tutorial.md
@@ -0,0 +1,424 @@
+<!--
+   Copyright 2012 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.
+-->
+
+# Tutorial
+
+This tutorial guides you through the construction of a "hello world" Trade Federation test
+configuration, and gives you a hands-on introduction to the Trade Federation framework.  Starting
+from the Tf development environment, it guides you through the process of creating a simple Trade
+Federation config and gradually adding more features to it.
+
+The tutorial presents the TF test development process as a set of exercises, each consisting of
+several steps.  The exercises demonstrate how to gradually build and refine your configuration, and
+provide all the sample code you need to complete the test configuration.
+
+When you are finished with the tutorial, you will have created a functioning TF configuration and
+will have learned many of the most important concepts in the TF framework.
+
+
+## Set up TradeFederation development environment
+
+See (FIXME: link) for how to setup the development environment. The rest of this tutorial assumes you have a shell open that has been initialized to the TradeFederation environment. 
+
+For simplicity, this tutorial will illustrate adding a configuration and its classes to the TradeFederation framework core library. Later tutorials/documentation will show how to create your own library that extends TradeFederation.
+
+
+## Creating a test class
+
+Lets create a hello world test that just dumps a message to stdout. A TradeFederation test must
+implement the (FIXME: link) IRemoteTest interface.
+
+Here's an implementation for the HelloWorldTest:
+
+    package com.android.tradefed.example;
+
+    import com.android.tradefed.device.DeviceNotAvailableException;
+    import com.android.tradefed.result.ITestInvocationListener;
+    import com.android.tradefed.testtype.IRemoteTest;
+
+
+    public class HelloWorldTest implements IRemoteTest {
+        @Override
+        public void run(ITestInvocationListener listener) throws DeviceNotAvailableException {
+            System.out.println("Hello, TF World!");
+        }
+    }
+
+FIXME: prod-tests
+Save this sample code to
+`<git home>/tools/tradefederation/prod-tests/src/com/android/tradefed/example/HelloWorldTest.java`
+and rebuild tradefed from your shell:
+
+    m -j6
+
+If the build does not succeed, please consult the (FIXME: link)Development Environment page to
+ensure you did not miss any steps.
+
+
+## Creating a configuration
+
+Trade Federation tests are defined in a "Configuration". A Configuration is an XML file that
+instructs tradefed which test (or set of tests) to run.
+
+Lets create a new Configuration for our HelloWorldTest.
+
+    <configuration description="Runs the hello world test">
+        <test class="com.android.tradefed.example.HelloWorldTest" />
+    </configuration>
+
+TF will parse the Configuration XML file, load the specified class using reflection, instantiate it,
+cast it to a IRemoteTest, and call its 'run' method.
+
+Note that we've specified the full class name of the HelloWorldTest. Save this data to a
+`helloworld.xml` file anywhere on your local filesystem (eg `/tmp/helloworld.xml`).
+
+
+## Running the configuration
+
+From your shell, launch the tradefed console
+
+    $ ./tradefed.sh
+
+Ensure a device is connected to the host machine that is visible to tradefed
+
+    tf> list devices
+
+Configurations can be run using the `run <config>` console command.  Try this now
+
+FIXME: redo this
+
+    tf> run /tmp/helloworld.xml
+    05-12 13:19:36 I/TestInvocation: Starting invocation for target stub on build 0 on device 30315E38655500EC
+    Hello, TF World!
+
+You should see "Hello, TF World!" outputted on the terminal.
+
+
+## Adding the configuration to the classpath
+FIXME: prod-tests
+For convenience of deployment, you can also bundle configuration files into the TradeFederation jars
+themselves. Tradefed will automatically recognize all configurations placed in 'config' folders on
+the classpath.
+
+Lets illustrate this now by moving the helloworld.xml into the tradefed core library.
+
+Move the `helloworld.xml` file into 
+`<git root>/tools/tradefederation/prod-tests/res/config/example/helloworld.xml`.
+
+Rebuild tradefed, and restart the tradefed console. 
+
+Ask tradefed to display the list of configurations on the classpath:
+
+    tf> list configs
+    […]
+    example/helloworld: Runs the hello world test
+
+You can now run the helloworld config via the following command
+
+    tf >run example/helloworld
+    05-12 13:21:21 I/TestInvocation: Starting invocation for target stub on build 0 on device 30315E38655500EC
+    Hello, TF World!
+
+
+## Interacting with a device
+
+So far our hello world test isn't doing anything interesting. Tradefed is intended to run tests using Android devices, so lets add an Android device to the test.
+
+Tests can get a reference to an Android device by implementing the IDeviceTest interface. 
+
+Here's a sample implementation of what this looks like:
+
+    public class HelloWorldTest implements IRemoteTest, IDeviceTest {
+        private ITestDevice mDevice;
+        @Override
+        public void setDevice(ITestDevice device) {
+            mDevice = device;
+        }
+
+        @Override
+        public ITestDevice getDevice() {
+            return mDevice;
+        }
+    …
+    }
+
+The TradeFederation framework will inject the ITestDevice reference into your test via the
+IDeviceTest#setDevice method, before the IRemoteTest#run method is called.
+
+Lets add an additional print message to the HelloWorldTest displaying the serial number of the
+device.
+
+    @Override
+    public void run(ITestInvocationListener listener) throws DeviceNotAvailableException {
+        System.out.println("Hello, TF World! I have a device " + getDevice().getSerialNumber());
+    }
+
+Now rebuild tradefed, and do (FIXME: update)
+
+    $ tradefed.sh
+    tf> list devices
+    Available devices:   [30315E38655500EC]
+    …
+
+Take note of the serial number listed in Available devices above. That is the device that should be allocated to HelloWorld.
+
+    tf >run example/helloworld
+    05-12 13:26:18 I/TestInvocation: Starting invocation for target stub on build 0 on device 30315E38655500EC
+    Hello world, TF! I have a device 30315E38655500EC
+
+You should see the new print message displaying the serial number of the device.
+
+
+## Sending test results
+
+IRemoteTests report results by calling methods on the ITestInvocationListener instance provided to
+their `#run` method.
+
+The TradeFederation framework is responsible for reporting the start and end of an Invocation (via
+the ITestInvocationListener#invocationStarted and ITestInvocationListener#invocationEnded methods
+respectively).
+
+A `test run` is a logical collection of tests. To report test results, IRemoteTests are responsible
+for reporting the start of a test run, the start and end of each test, and the end of the test run.
+
+Here's what the HelloWorldTest implementation looks like with a single failed test result.
+
+    @SuppressWarnings("unchecked")
+    @Override
+    public void run(ITestInvocationListener listener) throws DeviceNotAvailableException {
+        System.out.println("Hello, TF World! I have a device " + getDevice().getSerialNumber());
+
+        TestIdentifier testId = new TestIdentifier("com.example.MyTestClassName", "sampleTest");
+        listener.testRunStarted("helloworldrun", 1);
+        listener.testStarted(testId);
+        listener.testFailed(TestFailure.FAILURE, testId, "oh noes, test failed");
+        listener.testEnded(testId, Collections.EMPTY_MAP);
+        listener.testRunEnded(0, Collections.EMPTY_MAP);
+    }
+
+Note that TradeFederation also includes several IRemoteTest implementations that you can reuse
+instead of writing your own from scratch. (such as InstrumentationTest, which can run an Android
+application's tests remotely on an Android device, parse the results, and forward them to the
+ITestInvocationListener). See the Test Types documentation for more details.
+
+
+## Storing test results
+
+By default, a TradeFederation configuration will use the TextResultReporter as the test listener
+implementation for the configuration.  TextResultReporter will dump the results of an invocation to
+stdout. To illustrate, try running the hello-world config from previous section now:
+
+    $ ./tradefed.sh
+    tf >run example/helloworld
+    05-16 20:03:15 I/TestInvocation: Starting invocation for target stub on build 0 on device 30315E38655500EC
+    Hello world, TF! I have a device 30315E38655500EC
+    05-16 20:03:15 I/InvocationToJUnitResultForwarder: run helloworldrun started: 1 tests
+    Test FAILURE: com.example.MyTestClassName#sampleTest 
+     stack: oh noes, test failed 
+    05-16 20:03:15 I/InvocationToJUnitResultForwarder: run ended 0 ms
+
+If you want to store the results of an invocation elsewhere, say to a file, you would need to
+specify a custom "result_reporter" in your configuration, that specifies the custom
+ITestInvocationListener class you want to use.
+
+The TradeFederation framework includes a result_reporter (XmlResultReporter)  that will write test
+results to an XML file, in a format similar to the ant JUnit XML writer. 
+
+Lets specify the result_reporter in the configuration now. Edit the
+`tools/tradefederation/res/config/example/helloworld.xml` like this:
+
+    <configuration description="Runs the hello world test">
+        <test class="com.android.tradefed.example.HelloWorldTest" />
+        <result_reporter class="com.android.tradefed.result.XmlResultReporter" />
+    </configuration> 
+
+Now rebuild tradefed and re-run the hello world sample:
+FIXME: paths
+
+    tf >run example/helloworld
+    05-16 21:07:07 I/TestInvocation: Starting invocation for target stub on build 0 on device 30315E38655500EC
+    Hello world, TF! I have a device 30315E38655500EC
+    05-16 21:07:07 I/XmlResultReporter: Saved device_logcat log to /var/folders/++/++2Pz+++6+0++4RjPqRgNE+-4zk/-Tmp-/0/inv_2991649128735283633/device_logcat_6999997036887173857.txt
+    05-16 21:07:07 I/XmlResultReporter: Saved host_log log to /var/folders/++/++2Pz+++6+0++4RjPqRgNE+-4zk/-Tmp-/0/inv_2991649128735283633/host_log_6307746032218561704.txt
+    05-16 21:07:07 I/XmlResultReporter: XML test result file generated at /var/folders/++/++2Pz+++6+0++4RjPqRgNE+-4zk/-Tmp-/0/inv_2991649128735283633/test_result_536358148261684076.xml. Total tests 1, Failed 1, Error 0
+
+Notice the log message stating an XML file has been generated. The generated file should look like this:
+
+    <?xml version='1.0' encoding='UTF-8' ?>
+    <testsuite name="stub" tests="1" failures="1" errors="0" time="9" timestamp="2011-05-17T04:07:07" hostname="localhost">
+      <properties />
+      <testcase name="sampleTest" classname="com.example.MyTestClassName" time="0">
+        <failure>oh noes, test failed
+        </failure>
+      </testcase>
+    </testsuite>
+
+Note that you can write your own custom result_reporter. It just needs to implement the
+ITestInvocationListener interface. 
+
+Also note that Tradefed supports multiple result_reporters, meaning that you can send test results
+to multiple independent destinations. Just specify multiple <result_reporter> tags in your config to
+do this.
+
+
+## Logging
+
+TradeFederation includes two logging facilities:
+
+1. ability to capture logs from the device (aka device logcat)
+2. ability to record logs from the TradeFederation framework running on the host machine (aka the
+    host log)
+
+Lets focus on 2 for now. Trade Federation's host logs are reported using the CLog wrapper for the
+ddmlib Log class. 
+
+Lets convert the previous System.out.println call in HelloWorldTest to a CLog call:
+
+    @Override
+    public void run(ITestInvocationListener listener) throws DeviceNotAvailableException {
+        CLog.i("Hello world, TF! I have a device " + getDevice().getSerialNumber());
+
+Now rebuild and rerun. You should see the log message on stdout. 
+
+    tf> run example/helloworld
+    …
+    05-16 21:30:46 I/HelloWorldTest: Hello world, TF! I have a device 30315E38655500EC
+    …
+
+By default, TradeFederation will output host log messages to stdout. TradeFederation also includes a
+log implementation that will write messages to a file: FileLogger. To add file logging, add a
+'logger' tag to the configuration xml, specifying the full class name of FileLogger.
+
+    <configuration description="Runs the hello world test">
+        <test class="com.android.tradefed.example.HelloWorldTest" />
+        <result_reporter class="com.android.tradefed.result.XmlResultReporter" />
+        <logger class="com.android.tradefed.log.FileLogger" />
+    </configuration> 
+
+Now rebuild and run the helloworld example again.
+
+    tf >run example/helloworld 
+    …
+    05-16 21:38:21 I/XmlResultReporter: Saved device_logcat log to /var/folders/++/++2Pz+++6+0++4RjPqRgNE+-4zk/-Tmp-/0/inv_6390011618174565918/device_logcat_1302097394309452308.txt
+    05-16 21:38:21 I/XmlResultReporter: Saved host_log log to /tmp/0/inv_6390011618174565918/host_log_4255420317120216614.txt
+    …
+
+Note the log message indicating the path of the host log. View the contents of that file, and you
+should see your HelloWorldTest log message
+
+    $ more /tmp/0/inv_6390011618174565918/host_log_4255420317120216614.txt
+    …
+    05-16 21:38:21 I/HelloWorldTest: Hello world, TF! I have a device 30315E38655500EC
+
+The TradeFederation framework will also automatically capture the logcat from the allocated device,
+and send it the the result_reporter for processing. XmlResultReporter will save the captured device
+logcat as a file.
+
+
+## Command line options
+Objects loaded from a TradeFederation Configuration (aka "Configuration objects") also have the
+ability to receive data from command line arguments.
+
+This is accomplished via the `@Option` annotation. To participate, a Configuration object class
+would apply the `@Option` annotation to a member field, and provide it a unique name. This would
+allow that member field's value to be populated via a command line option, and would also
+automatically add that option to the configuration help system (Note: not all field types are
+supported: see the OptionSetter javadoc for a description of supported types).
+
+Lets add an Option to the HelloWorldTest.
+
+    @Option(name="my_option",
+            shortName='m',
+            description="this is the option's help text",
+            // always display this option in the default help text
+            importance=Importance.ALWAYS)
+    private String mMyOption = "thisisthedefault";
+
+And lets add a log message to display the value of the option in HelloWorldTest, so we can
+demonstrate that it was received correctly.
+
+    @SuppressWarnings("unchecked")
+    @Override
+    public void run(ITestInvocationListener listener) throws DeviceNotAvailableException {
+        …
+        Log.logAndDisplay(LogLevel.INFO, "HelloWorldTest", "I received this option " + mMyOption);
+
+Rebuild TF and run helloworld: you should see a log message with the my_option's default value.
+
+    tf> run example/helloworld
+    …
+    05-24 18:30:05 I/HelloWorldTest: I received this option thisisthedefault
+
+Now pass in a value for my_option: you should see my_option getting populated with that value
+
+    tf> run example/helloworld --my_option foo
+    …
+    05-24 18:33:44 I/HelloWorldTest: I received this option foo
+
+TF configurations also include a help system, which automatically displays help text for @Option
+fields. Try it now, and you should see the help text for 'my_option':
+
+    tf> run --help example/helloworld
+    Printing help for only the important options. To see help for all options, use the --help-all flag
+
+      cmd_options options:
+        --[no-]help          display the help text for the most important/critical options. Default: false.
+        --[no-]help-all      display the full help text for all options. Default: false.
+        --[no-]loop          keep running continuously. Default: false.
+
+      test options:
+        -m, --my_option      this is the option's help text Default: thisisthedefault.
+
+      'file' logger options:
+        --log-level-display  the minimum log level to display on stdout. Must be one of verbose, debug, info, warn, error, assert. Default: error.
+FIXME: redo with enum help
+
+Note the message at the top about 'printing only the important options'. To reduce option help
+clutter, TF uses the Option#importance attribute to determine whether to show an Option's help text
+when '--help' is specified. '--help-all' will always show all options' help regardless of
+importance. See Option.Importance javadoc for details.
+
+You can also specify an Option's value within the configuration xml by adding a
+`<option name="" value="">` element. Lets see how this looks in the helloworld.xml:
+
+    <test class="com.android.tradefed.example.HelloWorldTest" >
+        <option name="my_option" value="fromxml" />
+    </test>
+
+Re-building and running helloworld should now produce this output:
+
+    05-24 20:38:25 I/HelloWorldTest: I received this option fromxml
+
+The configuration help should also be updated to indicate my_option's new default value:
+
+    tf> run --help example/helloworld
+      test options:
+        -m, --my_option      this is the option's help text Default: fromxml.
+
+Also note that other configuration objects included in the helloworld config, like FileLogger, also have options. '--log-level-display' is of interest because it filters the logs that show up on stdout. You may have noticed from earlier in the tutorial the 'Hello world, TF! I have a device ..' log message stopped getting displayed on stdout once we switched to using FileLogger. You can increase the verbosity of logging to stdout by passing in log-level-display arg.
+
+Try this now, and you should see the 'I have a device' log message reappear on stdout, in addition to getting logged to a file.
+
+    tf >run --log-level-display info example/helloworld
+    …
+    05-24 18:53:50 I/HelloWorldTest: Hello world, TF! I have a device XXXXXX
+
+<!-- To make future debugging in this tutorial easier, edit the helloworld.xml to default log-level-display to debug:
+
+    <logger class="com.android.tradefed.log.FileLogger" >
+        <option name="log-level-display" value="debug" />
+    </logger>
+-->