Work-in-progress snapshot of the source.android.com (formerly PDK) site
refresh.
diff --git a/pdk/docs/compatibility/compatibility_toc.cs b/pdk/docs/compatibility/compatibility_toc.cs
index 3952495..8e16bc8 100644
--- a/pdk/docs/compatibility/compatibility_toc.cs
+++ b/pdk/docs/compatibility/compatibility_toc.cs
@@ -5,23 +5,17 @@
</script>
<ul>
- <li> <h2>Program Details </h2>
- <ul>
- <li><a href="">Program Overview</a></li>
- <li><a href="">Getting Started</a></li>
- <li><a href="">Contact Us</a></li>
- </ul>
- </li>
+ <li><h2>Getting Started</h2><ul>
+ <li><a href="<?cs var:toroot ?>compatibility/overview.html">Compatibility Overview</a></li>
+ <li><a href="">Current CDD</a></li>
+ <li><a href="<?cs var:toroot ?>compatibility/cts-intro.html">CTS Introduction</a></li>
+ </ul></li>
- <li> <h2>Compatibility Tools </h2>
- <ul>
- <li><a href="">Compatibility Definition</a></li>
- <li><a href="">Compatibility Test Suite</a></li>
- <li><a href="">Compatibility FAQ</a></li>
- <li><a href="">Downloads</a></li>
- </ul>
- </li>
-
+ <li><h2>More Information</h2><ul>
+ <li><a href="<?cs var:toroot ?>downloads/index.html">Downloads</a></li>
+ <li><a href="<?cs var:toroot ?>compatibility/faq.html">FAQ</a></li>
+ <li><a href="<?cs var:toroot ?>compatibility/contact-us.html">Contact Us</a></li>
+ </ul></li>
</ul>
<script type="text/javascript">
diff --git a/pdk/docs/compatibility/contact-us.jd b/pdk/docs/compatibility/contact-us.jd
new file mode 100644
index 0000000..92062ba
--- /dev/null
+++ b/pdk/docs/compatibility/contact-us.jd
@@ -0,0 +1,28 @@
+page.title=Android Compatibility - Contact Us
+doc.type=compatibility
+@jd:body
+<h3><b>Mailing list</b>
+</h3>
+<div><div>Welcome to the Android compatibility mailing list!<br>
+To get the most out of the mailing list discussions, please do the following before you post:
+<ol><li><b>Read the<a href="http://sites.google.com/a/android.com/opensource/discuss/android-discussion-groups-charter">mailing list charter</a>
+</b>
+that covers the community guidelines.<br><br></li>
+<li><b>Search the mailing list archives</b>
+to see whether your questions have already been discussed.<br><br></li>
+<li><b>Be very clear</b>
+about your question in the subject -- it helps everyone, both those trying to answer your question as well as those who may be looking for information in the future.<br><br></li>
+<li><b>Give plenty of details</b>
+in your post to help others understand your problem. Code or log snippets, as well as pointers to screenshots, may also be helpful. For a great guide to phrasing your questions, read<a href="http://www.google.com/url?q=http%3A%2F%2Fwww.catb.org%2F%257Eesr%2Ffaqs%2Fsmart-questions.html&sa=D&sntz=1&usg=AFrqEzd169OWM-dgsNW_9rDKrOgOJqgpEA">How To Ask Questions The Smart Way</a>
+.
+</li>
+</ol>
+<br>There are two ways to join the Android compatibility mailing list:<br></div>
+<ul><li>Visit the<a href="http://groups.google.com/group/android-compatibility">android-compatibility sign-up page</a>
+on Google Groups, or
+</li>
+<li>Send email to<a href="mailto:android-compatibility-subscribe@googlegroups.com">android-compatibility-subscribe@googlegroups.com</a>
+.
+</li>
+</ul>
+</div>
diff --git a/pdk/docs/compatibility/cts-intro.jd b/pdk/docs/compatibility/cts-intro.jd
new file mode 100644
index 0000000..b575b11
--- /dev/null
+++ b/pdk/docs/compatibility/cts-intro.jd
@@ -0,0 +1,98 @@
+page.title=Android Compatibility - Compatibility Test Suite
+doc.type=compatibility
+@jd:body
+<h3><b>Compatibility test suite (CTS)</b>
+</h3>
+<b>Contents</b>
+<ol>
+<li><a href="#TOC-How-does-the-CTS-work-">How does the CTS work?</a></li>
+<li><a href="#TOC-Workflow">Workflow</a></li>
+<li><a href="#TOC-Types-of-test-cases">Types of test cases</a></li>
+<li><a href="#TOC-Areas-Covered">Areas Covered</a></li>
+</ol>
+
+<h3>How does the CTS work?</h3>
+<div><img src="{@docRoot}images/cts-0.png"></div>
+<div>The CTS is an automated testing harness that includes two major software components:</div>
+<ul>
+<li>The CTS test harness runs on your desktop machine and manages test execution.</li>
+<li>Individual test cases are executed on attached mobile devices or on an emulator. The test cases are written in Java as JUnit tests and packaged as Android .apk files to run on the actual device target.</li>
+</ul>
+
+<h3>Workflow</h3>
+<ol>
+<li>Use the bundled CTS release or download the CTS from the Android Open Source Project onto your desktop machine.</li>
+<li>Install and configure the CTS.</li>
+<li>Attach at least one device (or emulator) to your machine.</li>
+<li>Launch the CTS. The CTS test harness loads the test plan onto the attached devices. For each test in the test harness:
+ <ul>
+ <li>The test harness pushes a .apk file to each device, executes the test through instrumentation, and records test results.</li>
+ <li>The test harness removes the .apk file from each device.</li>
+ </ul>
+</li>
+<li>Once all the tests are executed, you can view the test results in your browser and use the results to adjust your design. You can continue to run the CTS throughout your development process.</li>
+<li>If you see test failures, follow the instructions on the<a href="http://sites.google.com/a/android.com/compatibility/compatibility-faq">Compatibility FAQ</a>
+page.</li>
+</ol>
+<div>When you are ready, you can submit the report generated by the CTS to cts@android.com. The report is a .zip archived file that contains XML results and supplemental information such as screen captures.</div>
+
+<h3>Types of test cases</h3>
+The CTS includes the following types of test cases:
+<ul>
+<li><i>Unit tests</i> test atomic units of code within the Android platform; e.g. a single class, such as java.util.HashMap.</li>
+<li><i>Functional tests</i> test a combination of APIs together in a higher-level use-case.</li>
+<li><i>Reference application tests</i> instrument a complete sample application to exercise a full set of APIs and Android runtime services</li>
+</ul>
+<div>Future versions of the CTS will include the following types of test cases:</div>
+<ul>
+<li><i>Robustness tests</i> test the durability of the system under stress.</li>
+<li><i>Performance tests</i> test the performance of the system against defined benchmarks, for example rendering frames per second.</li>
+</ul>
+
+<h3>Areas Covered</h3>
+The unit test cases cover the following areas to ensure compatibility<br>
+<table><tbody>
+<tr><td>Area</td><td>Description<br></td></tr>
+<tr><td>Signature tests</td>
+<td>For each Android release, there are XML files describing the signatures of all public APIs contained in the release. The CTS contains a utility to check those API signatures against the APIs available on the device. The results from signature checking are recorded in the test result XML file.
+</td>
+</tr>
+<tr><td>Platform API Tests</td>
+<td>Test the platform (core libraries and Android Application Framework) APIs as documented in the SDK<a href="http://code.google.com/android/reference/classes.html">Class Index</a>
+to ensure API correctness:
+<ul>
+<li>correct class, attribute and method signatures</li>
+<li>correct method behavior</li>
+<li>negative tests to ensure expected behavior for incorrect parameter handling</li>
+</ul>
+</td></tr>
+<tr><td>Dalvik VM Tests</td><td>The tests focus on testing the Dalvik VM</td></tr>
+<tr><td>Platform Data Model</td>
+<td>The CTS tests the core platform data model as exposed to application developers through content providers, as documented in the SDK<a href="http://code.google.com/android/reference/android/provider/package-summary.html">android.provider</a>
+package:
+<ul>
+<li>contacts</li>
+<li>browser</li>
+<li>settings</li>
+<li>more...</li>
+</ul>
+</td></tr>
+<tr><td>Platform Intents</td>
+<td>The CTS tests the core platform intents, as documented in the SDK<a href="http://code.google.com/android/reference/available-intents.html">Available Intents</a>.</td>
+</tr>
+<tr><td>Platform Permissions</td>
+<td>The CTS tests the core platform permissions, as documented in the SDK<a href="http://code.google.com/android/reference/android/Manifest.permission.html">Available Permissions</a>.</td>
+</tr>
+<tr><td>Platform Resources<br></td>
+<td>The CTS tests for correct handling of the core platform resource types, as documented in the SDK<a href="http://code.google.com/android/reference/available-resources.html">Available Resource Types</a>
+. This includes tests for:
+<ul>
+<li>simple values</li>
+<li>drawables</li>
+<li>nine-patch</li>
+<li>animations</li>
+<li>layouts</li>
+<li>styles and themes</li>
+<li>loading alternate resources</li>
+</ul></td></tr>
+</tbody></table>
diff --git a/pdk/docs/compatibility/faq.jd b/pdk/docs/compatibility/faq.jd
new file mode 100644
index 0000000..71a193d
--- /dev/null
+++ b/pdk/docs/compatibility/faq.jd
@@ -0,0 +1,124 @@
+page.title=Android Compatibility - Frequently Asked Questions
+doc.type=compatibility
+@jd:body
+
+<h3><b>Compatibility FAQ</b></h3>
+<div><div><div><div><div><div><p><b>Contents</b>
+</p>
+<ol><li><a href="#TOC-The-CTS-report-shows-test-failures-"><b>1</b>
+The CTS report shows test failures -- what should I do now?</a>
+</li>
+<li><a href="#TOC-Android-1.5-CTS-r1-known-issues"><b>2</b>
+Android 1.5 CTS r1 known issues</a>
+</li>
+<li><a href="#TOC-Can-I-remove-the-final-modifier-fro"><b>3</b>
+Can I remove the 'final' modifier from classes in the Android public APIs and still be an Android-compatible device?</a>
+</li>
+<li><a href="#TOC-I-see-a-failure-in-my-report-with-t"><b>4</b>
+I see a failure in my report with the comment "A test that was a known failure actually passed. Please check." -- what does this mean?</a>
+</li>
+<li><a href="#TOC-Why-are-compass-and-accelerometer-r"><b>5</b>
+Why are compass and accelerometer required for Android compatibility?</a>
+</li>
+</ol>
+</div>
+</div>
+</div>
+</div>
+</div>
+<h3>
+The CTS report shows test failures -- what should I do now?
+</h3>
+<div><div><b>Step 1: Get the latest CTS version.</b>
+Make sure you are running the latest version of CTS -- check if your version is the same as the one posted on the<a href="http://sites.google.com/a/android.com/compatibility/download-cts">Downloads</a>
+page. If not, make sure you update to the latest version and re-run CTS. As we find issues in CTS, we push out new versions with fixes to the tests and/or frame-work. Using the latest version minimizes the chances of you facing any CTS specific issues.
+</div>
+<div><br></div>
+<div><b>Step 2: Investigate the CTS source code.</b>
+Make sure you have grabbed the CTS sources provided on the<a href="http://sites.google.com/a/android.com/compatibility/download-cts">Download</a>
+page. Then unzip the CTS report zip$CTS_ROOT/repository/results/start time.zipand opentestResult.xmlin your favorite browser. Find the exception next to the failing test and check the corresponding source file for possible failure causes.</div>
+<div><br></div>
+<div><b>Step 3: Fix the error in your source and re-run CTS.</b>
+Once you have located the cause of failure in your source code, fix it and re-run CTS.
+</div>
+<div><br></div>
+<div><b>Step 4: The test is broken.</b>
+If you think the CTS test is incorrect or is not testing things the right way, shoot a detailed email to cts@android.com with the following information at the minimum - the failing test, why you think the CTS test is broken, your CTS test report and the log generated by your CTS run (text file in the$CTS_ROOT/repository/results/directory corresponding to timestamp of run).</div>
+<div><br></div>
+<h3>
+Android 1.5 CTS r1 known issues
+</h3>
+<div>android.app.cts.ActivityManagerTest#testGetRunningServices - known issue test, waived automatically</div>
+<div>android.graphics.cts.BitmapTest#testCopyPixelsToBuffer - can be an issue if device uses a pixel format like ARGB (4 bytes per pixel)</div>
+<div>tests.api.java.io.OutputStreamWriterTest.test_write$C(OutputStreamWriterTest.java:470) - test breaks in 1.5 r3</div>
+<div><br></div>
+<div><b>The following tests have known issues with non en_US locales:</b>
+</div>
+<div>tests.api.java.io.PrintStreamTest#test_formatLjava_util_Locale_Ljava_lang_String_$Ljava_lang_Object<br>tests.api.java.io.PrintStreamTest#test_printfLjava_util_Locale_Ljava_lang_String_$Ljava_lang_Object<br>tests.api.java.io.PrintWriterTest#test_formatLjava_util_Locale_Ljava_lang_String_$Ljava_lang_Object<br>tests.api.java.io.PrintWriterTest#test_printfLjava_util_Locale_Ljava_lang_String_$Ljava_lang_Object<br>tests.api.java.util.CalendarTest#test_hashCode<br>tests.api.java.util.CalendarTest#test_getFirstDayOfWeek<br>tests.api.java.util.CalendarTest#test_getInstanceLjava_util_Locale<br>tests.api.java.util.CalendarTest#test_getInstanceLjava_util_TimeZoneLjava_util_Locale<br>tests.api.java.util.CalendarTest#test_getMinimalDaysInFirstWeek<br>tests.api.java.util.FormatterTest#test_formatLjava_lang_String$Ljava_lang_Object_ByteShortIntegerLongConversionD<br>tests.api.java.util.FormatterTest#test_formatLjava_lang_String$Ljava_lang_Object_DateTimeConversion<br>tests.api.java.util.FormatterTest#test_formatLjava_lang_String$LBigInteger<br>tests.api.java.util.FormatterTest#test_formatLjava_lang_String$Ljava_lang_Object_BigIntegerPaddingConversion<br>tests.api.java.util.FormatterTest#test_formatLjava_util_LocaleLjava_lang_StringLjava_lang_Object<br>tests.api.java.util.GregorianCalendarTest#test_ConstructorLjava_util_Locale<br>tests.api.java.util.LocaleTest#test_getDisplayCountryLjava_util_Locale<br>tests.api.java.util.LocaleTest#test_getDisplayLanguageLjava_util_Locale<br>tests.api.java.util.LocaleTest#test_getDisplayNameLjava_util_Locale<br>tests.api.java.util.ScannerTest#test_nextDouble<br>tests.api.java.util.ScannerTest#test_nextFloat<br>tests.api.java.util.ScannerTest#test_nextInt<br>tests.api.java.util.ScannerTest#test_nextIntI<br>tests.api.java.util.ScannerTest#test_nextLong<br>tests.api.java.util.ScannerTest#test_nextShortI<br>tests.api.java.util.ScannerTest#test_nextShort<br>tests.api.java.util.ScannerTest#test_nextLongI<br>tests.api.java.util.ScannerTest#test_hasNextIntI<br>tests.api.java.util.ScannerTest#test_hasNextInt<br>tests.api.java.util.ScannerTest#test_hasNextFloat<br>tests.api.java.util.ScannerTest#test_hasNextShortI<br>tests.api.java.util.ScannerTest#test_hasNextShort<br>tests.api.java.util.ScannerTest#test_hasNextLongI<br>tests.api.java.util.ScannerTest#test_hasNextLong<br>tests.api.java.util.ScannerTest#test_hasNextDouble<br>tests.api.java.util.ScannerTest#test_hasNextBigDecimal<br>tests.api.java.util.ScannerTest#test_nextBigDecimal<br>tests.api.java.util.TimeZoneTest#test_getDisplayNameLjava_util_Locale<br>tests.api.java.util.TimeZoneTest#test_getDisplayNameZILjava_util_Locale<br>org.apache.harmony.text.tests.java.text.DateFormatTest#test_getAvailableLocales<br>org.apache.harmony.text.tests.java.text.DecimalFormatSymbolsTest#test_getCurrency<br>org.apache.harmony.text.tests.java.text.DecimalFormatTest#test_formatToCharacterIteratorLjava_lang_Object<br>org.apache.harmony.text.tests.java.text.NumberFormatTest#test_getInstanceLjava_util_Locale<br>org.apache.harmony.text.tests.java.text.NumberFormatTest#test_parseObjectLjava_lang_StringLjava_text_ParsePosition<br>org.apache.harmony.text.tests.java.text.NumberFormatTest#test_getIntegerInstanceLjava_util_Locale<br>org.apache.harmony.text.tests.java.text.NumberFormatTest#test_formatLdouble<br>org.apache.harmony.text.tests.java.text.NumberFormatTest#test_formatLlong<br>org.apache.harmony.text.tests.java.text.NumberFormatTest#test_getCurrencyInstanceLjava_util_Locale<br>org.apache.harmony.text.tests.java.text.NumberFormatTest#test_getNumberInstanceLjava_util_Locale<br>org.apache.harmony.text.tests.java.text.NumberFormatTest#test_getPercentInstanceLjava_util_Locale<br>org.apache.harmony.text.tests.java.text.NumberFormatTest#test_setGroupingUsed<br><br></div>
+<div><br></div>
+<h3>
+Can I remove the 'final' modifier from classes in the Android public APIs and still be an Android-compatible device?
+</h3>
+<div>Let's take the following example, where you want to extend the base Contacts class to create your own version of the class. Android 1.5 supports SDK add-ons that OEMs can create to expose new functionality and platform APIs specific to the phone. However, the SDK add-on architecture does not allow the add-on provider to include their own android.jar Thus, when you expose your new Contacts class (which expects to extend the base Contacts class) developers using your add-on plugin will be unable to compile and run their applications against the standard android.jar containing the *final* Contacts class.</div>
+<div><div><br></div>
+<div>The recommended approach is to create a new class with the specific fields that you want to add and access these fields from the new class. This will not only ensure compatibility but will also ensure a safer and easier update path when the Android schema/implementation changes with future releases. This is illustrated in the following example:</div>
+<div><div><br></div>
+<div><p>public /* final */ class BaseClass {</p>
+<p>/* private */ protected BaseClass() { }</p>
+<br>
+<p>public static final String SOME_FIELD = "base";</p>
+<p>// If this is declared final, WrongApproach.java won't compile.</p>
+<p>// In Contacts.People, it is not declared final (it didn't need to since the class was final)</p>
+<p>public static /* final */ String frungulate() { return "foo"; }</p>
+<p>}</p>
+<br>
+<p>public final class CorrectApproach {</p>
+<p>public static final String SOME_FIELD = "some";</p>
+
+<p>public static final String frungulate() { return "bar"; }</p>
+<p>}</p>
+<br>
+<p>public class WrongApproach extends BaseClass {</p>
+<p>public static final String SOME_FIELD = "some";</p>
+
+<p>public static final String frungulate() { return "bar"; }</p>
+
+<p>public static void main(String[] args) {</p>
+<p>WrongApproach m = new WrongApproach();</p>
+<p>System.out.println(m.SOME_FIELD);</p>
+<p>System.out.println(m.frungulate());</p>
+
+<p>// What should be done...</p>
+<p>System.out.println(CorrectApproach.SOME_FIELD);</p>
+<p>System.out.println(CorrectApproach.frungulate());</p>
+<p>}</p>
+<p>}</p>
+</div>
+<div></div>
+</div>
+</div>
+<div><br></div>
+<h3>
+I see a failure in my report with the comment "A test that was a known failure actually passed. Please check." -- what does this mean?
+</h3>
+<div>A "known failure" test is one that fails when run against our own implementation on G1 or Magic, hence it gets tagged as such and does not count towards your failure. However, if the test suddenly starts passing on your implementation this is not the expected result causing it to show up as a failure then.
+</div>
+<div><br>You should dig into the test source to see whats happening underneath.<br><br></div>
+<h3>
+Why are compass and accelerometer required for Android compatibility?
+</h3>
+<div>Whenever possible, we try to open up hardware options by making the Android software smarter.For example, in Android 1.5 we added an Input Method Framework and soft keyboard so that devices didn't need physical text input devices.The Android<i>Donut</i>
+release will the ability to scale application windows to different densities and resolutions so that devices aren't restricted to 160-180dpi HVGA displays.<br><br>Unfortunately, software can only do so much, and a compass and accelerometer are things Android cannot replace with software.These two input devices are now commonly used by applications.For example, many of the most popular applications in Android Market:<br><br>-<a href="http://www.android.com/market/featured.html#app=skymap"><i>Google Sky Map</i>
+</a>
+uses compass and accelerometer<br>-<a href="http://www.android.com/market/free.html#app=labyrinth"><i>Labyrinth</i>
+</a>
+uses accelerometer<br>-<a href="http://www.android.com/market/free.html#app=bonsaiblast"><i>Bonzai Blast</i>
+</a>
+uses accelerometer<br>-<a href="http://www.android.com/market/featured.html#app=wikitude"><i>Wikitude</i>
+</a>
+uses compass and accelerometer<br>-<a href="http://www.android.com/market/featured.html#app=zagatnru"><i>Zagat</i>
+</a>
+uses compass<br><br>As Market has no way of knowing whether an application uses these controls, we would not be able to filter these out of Android Market for devices which don't have the required hardware.This would create a bad user experience and could hurt the Android ecosystem if developers can no longer rely on these features in handsets, or receive bad reviews from consumers who have devices which can't support the features.<br></div>
+<div><br></div>
+</div>
+</div>
diff --git a/pdk/docs/compatibility/index.jd b/pdk/docs/compatibility/index.jd
index 964fdf7..9f62872 100644
--- a/pdk/docs/compatibility/index.jd
+++ b/pdk/docs/compatibility/index.jd
@@ -1,11 +1,60 @@
-home=true
+page.title=Android Compatibility
doc.type=compatibility
@jd:body
+<p>Android is an open source product, and anyone can use the source code to build
+devices. Incautious implementations, however, can easily introduce bugs that
+cause third-party applications to break. The purpose of the Android
+Compatibility Program is to help Android device implementations remain
+compatible with all apps.</p>
+<h2>Why build compatible Android devices?</h2>
+<h3>Users want a customizable device.</h3>
+<p>A mobile phone is a highly personal, always-on, always-present gateway to
+the Internet. We haven't met a user yet who didn't want to customize it by
+extending its functionality. That's why Android was designed as a robust
+platform for running after-market applications.</p>
-<div id="mainBodyFixed">
+<h3>Developers outnumber us all.</h3>
+<p>No device manufacturer can hope to write all the software that anyone could
+conceivably need. We need third-party developers to write the apps users want,
+so the Android Open Source Project aims to make it as easy and open as
+possible for developers to build apps.</p>
-<p>
-Compatibility start page goes here
-</p>
+<h3>Everyone needs a common ecosystem.</h3>
+<p>Every line of code developers write to work around a particular phone's bug
+is a line of code that didn't add a new feature. The more compatible phones
+there are, the more apps there will be. By building a fully compatible Android
+device, you benefit from the huge pool of apps written for Android, while
+increasing the incentive for developers to build more of those apps.</p>
-</div>
+
+<h2>Android compatibility is free, and it's easy.</h2>
+<p>If you are building a mobile device, you can follow these steps to make
+sure your device is compatible with Android. For more details about the
+Android compatibility program in general, see <a
+href="{@docRoot}compatibility/overview.html">the program overview</a>.</p>
+<p>Building a compatible device is a four-step process:</p>
+<ol>
+ <li><b>Obtain the Android software stack source code</b><p>This is the
+ <a href="{@docRoot}source/index.html">source code for the Android
+ platform</a>, that you port to your hardware.</p></li>
+ <li><b>Comply with Android Compatibility Definition Document</b><p>
+ This document enumerates the software and the hardware features of
+ a compatible Android device.</p></li>
+ <li><b>Pass the Compatibility Test Suite (CTS)</b><p>You can use the CTS
+ as an ongoing aid to compatibility during the development process.</p></li>
+ <li><b>Submit CTS report</b><p>[Optional] You can also submit your CTS report,
+ so that it can be validated and recorded.</p><p><i>Note:
+ the submission system is currently under construciton, and is not currently
+ available.</i></p></li>
+</ol>
+
+<h2>Benefits of compatibility</h2>
+<p>By submitting a validated CTS report, you receive public recognition of
+your device's compatibility. This also opens up additional options you can
+pursue such as use of the Android branding, access to Android Market, and
+more.</p>
+<p>As a consequence of some legal quirks, we aren't able to offer automatic
+licensing of either the Android Market or branding. To actually obtain access
+to these programs, you will need to <a
+href="{@docRoot}compatibility/contact-us.html">contact us</a> to obtain a
+license.</p>
diff --git a/pdk/docs/compatibility/overview.jd b/pdk/docs/compatibility/overview.jd
new file mode 100644
index 0000000..039e2c2
--- /dev/null
+++ b/pdk/docs/compatibility/overview.jd
@@ -0,0 +1,88 @@
+page.title=Compatibility Program Overview
+doc.type=compatibility
+@jd:body
+<p>The Android compatibility program makes it easy for mobile device
+manufacturers to develop compatible Android devices.</p>
+<h3>Program goals</h3>
+<p>The Android compatibility program works for the benefit of the entire
+Android community, including users, developers, and device manufacturers.</p>
+<p>Each group depends on the others. Users want a wide selection of devices
+and great apps; great apps come from developers motivated by a large market
+for their apps with many devices in users' hands; device manufacturers rely
+on a wide variety of great apps to increase their products' value for
+consumers.</p>
+<p>Our goals were designed to benefit each of these groups:</p>
+<ul>
+<li><b>Provide a consistent application and hardware environment to application
+developers.</b><p>Without a strong compatibility standard, devices can vary so
+greatly that developers must design different versions of their applications
+for different devices. The compatibility program provides a precise definition
+of what developers can expect from a compatible device in terms of APIs and
+capabilities. Developers can use this information to make good design
+decisions, and be confident that their apps will run well on any compatible
+device.</p></li>
+<li><b>Enable a consistent application experience for consumers.</b><p>If an
+application runs well on one compatible Android device, it should run well on
+any other device that is compatible with the same Android platform version.
+Android devices will differ in hardware and software capabilities, so the
+compatibility program also provides the tools needed for distribution systems
+such as Android Market to implement appropriate filtering. This means that
+users can only see applications which they can actually run.</p></li>
+<li><b>Enable device manufacturers to differentiate while being
+compatible.</b><p>The Android compatibility program focuses on the aspects of
+Android relevant to running third-party applications, which allows device
+manufacturers the flexibility to create unique devices that are nonetheless
+compatible.</p></li>
+<li><b>Minimize costs and overhead associated with
+compatibility.</b><p>Ensuring compatibility should be easy and inexpensive to
+device manufacturers. The testing tool (CTS) is free and will soon be available
+in open source. CTS is designed to be used for continuous self-testing during
+the device development process to eliminate the cost of changing your workflow
+or sending your device to a third party for testing. Meanwhile, there are no
+required certifications, and thus no corresponding costs and fees.</p></li>
+</ul>
+<p>The Android compatibility program consists of three key components:</p>
+<ul>
+<li>The source code to the Android software stack</li>
+<li>The Compatilbility Definition Document, representing the "policy"
+aspect of compatibility</li>
+<li>The Compatilbility Test Suite, representing the "mechanism" of compatibility</li>
+</ul>
+<p>Just as each version of the Android platform exists in a separate branch in
+the source code tree, there is a separate CTS and CDD for each version as
+well. The CDD, CTS, and source code are -- along with your hardware and your
+software customizations -- everything you need to create a compatible device.</p>
+
+<h3>Compatibility Definition Document (CDD)</h3>
+<p>For each release of the Android platform, a detailed Compatibility
+Definition Document (CDD) will be provided. The CDD represents the "policy"
+aspect of Android compatibility.</p>
+<p>No test suite, including CTS, can truly be comprehensive. For instance, the
+CTS includes a test that checks for the presence and correct behavior of
+OpenGL graphics APIs, but no software test can verify that the graphics
+actually appear correctly on the screen. More generally, it's impossible to
+test the presence of hardware features such as keyboards, display density,
+WiFi, and Bluetooth.</p>
+<p>The CDD's role is to codify and clarify specific requirements, and
+eliminate ambiguity. The CDD does not attempt to be comprehensive. Since
+Android is a single corpus of open-source code, the code itself is the
+comprehensive "specification" of the platform and its APIs. The CDD acts as a
+"hub", referencing other content (such as SDK API documentation) that provides
+a framework in which the Android source code may be used so that the end
+result is a compatible system.</p>
+<p>If you want to build a device compatible with a given Android version,
+start by checking out the source code for that version, and then read the
+corresponding CDD and stay within its guidelines. For additional details,
+simply examine <a href="">the latest CDD</a>.</p>
+
+<h3>Compatibility Test Suite (CTS)</h3>
+<p>The CTS is a free, commercial-grade test suite, available along with the
+Android source code. The CTS represents the "mechanism" of compatibility.</p>
+<p>The CTS runs on a desktop machine and executes test cases directly on
+attached devices or an emulator. The CTS is a set of unit tests designed to be
+integrated into the daily workflow (such as via a continuous build system) of
+the engineers building a device. Its intent is to reveal incompatibilities
+early on, and ensure that the software remains compatible throughout the
+development process.</p>
+<p>For details on the CTS, consult the <a
+href="{@docRoot}compatibility/cts-intro.html">CTS introduction</a>.</p>