AI 147780: add summary of "future-proofing your apps" and links

  to the blog post
  BUG=1790234

Automated import of CL 147780

diff --git a/docs/html/sdk/1.5_r1/upgrading.jd b/docs/html/sdk/1.5_r1/upgrading.jd
index 0b7312b..8071f49 100644 (file)
--- a/docs/html/sdk/1.5_r1/upgrading.jd
+++ b/docs/html/sdk/1.5_r1/upgrading.jd
@@ -25,13 +25,17 @@ sdk.version=1.5_r1
         <li><a href="#AntUsers">Ant Users</a></li>
       </ol>
     </li>
-    <li><a href="#MigrateYourApplications">Migrate Your Applications</a></li>
+    <li><a href="#MigrateYourApplications">Migrate Your Applications</a>
+      <ol><li><a href="#FutureProofYourApps">Future-proof your apps</a></li></ol>
+    </li>
   </ol>
   
   <h2>Migrating references</h2>
   <ol>
     <li><a href="{@docRoot}sdk/api_diff/3/changes.html">Android 1.5 API Differences</a></li>
- <!--   <li><a href="">TODO: LINK TO DAN'S POST &raquo;</a></li> -->
+    <li><a 
+href="http://android-developers.blogspot.com/2009/04/future-proofing-your-apps.html">Future-Proofing
+Your Apps &raquo;</a></li>
     <li><a 
 href="http://android-developers.blogspot.com/2009/04/ui-framework-changes-in-android-15.html">UI 
 framework changes in Android 1.5 &raquo;</a></li>
@@ -151,7 +155,7 @@ uninstall procedure and continue to <a href="#installAdt">Install the 0.9 ADT pl
     <li>Select the Android plugin entry by checking the box next to it, 
       then click <strong>Finish</strong>.
       <p>(Your original entry for the plugin should still be here. If not, see the guide
-      to <a href="{docRoot}sdk/1.5_r1/installing.html#installingplugin">Installing the ADT Plugin</a>.)
+      to <a href="{@docRoot}sdk/1.5_r1/installing.html#installingplugin">Installing the ADT Plugin</a>.)
       </p></li>
     <li>In the results, be sure that "Developer Tools" is checked, then click <strong>Next</strong>.</li>
     <li>Read and accept the license agreement, then click <strong>Next</strong>.
@@ -330,18 +334,55 @@ your project and make any necessary changes to your code.</p>
 in Eclipse, changing the "build target" to one using the Android 1.5 platform,
 and see where the ADT identifies errors in your code.</p>
 
+
+<h3 id="FutureProofYourApps">Future-proof your apps</h3>
+
 <p>There have been several API additions made for this release, but there have been
 very few actual API <em>changes</em>. Only a couple (relatively unused) elements 
 have been removed and a few have been deprecated, so your applications written with the 
-Android 1.1 system library should work just fine.
-Your application will be at highest risk of breakage if it uses Android APIs 
-that are not available in the public API documentation
-or if it explicitly depends on system bugs. For information
-about changes made to Android 1.5, refer to the following documents:</p>
+Android 1.1 system library should work just fine. However, 
+your application is more likely to encounter problems on Android 1.5
+if it performs any of the following:</p>
+
+<ul>
+  <li>Uses internal APIs. That is, APIs that are not officially supported
+  and not available in the reference documentation. Any un-official APIs are always subject
+  to change (which is why they're un-official) and some have indeed changed.
+  </li>
+  <li>Directly manipulates system settings. There are some settings (such as
+  GPS, data roaming, bluetooth and others) that used to be writable by 
+  applications but have been changed so that they can only be explicitly modified by the user
+  through the system settings. Refer to {@link android.provider.Settings.Secure}
+  to see which settings are now secured and cannot be directly changed by your application.
+  </li>
+  <li>Uses View hierarchies that are unreasonably deep (more than 10 or so levels) or 
+  broad (more than 30 total). View hierarchies this big have always been troublesome, but 
+  Android 1.5 is much more efficient at exposing this and your application may crash.
+  </li>
+  <li>Makes assumptions about the available hardware. With new support for soft keyboards,
+  not all devices will have full QWERTY keyboards on the hardware. So if your application
+  listens for special keypress events that only occur on a keypad, then your application
+  should degrade gracefully when there is no keyboard available.
+  </li>
+  <li>Performs its own layout orientation changes based on the acceletometer (or via other
+  sensors). Some devices running Android 1.5 will automatically rotate the orientation
+  (and all devices have the option to turn on auto-rotation), so if your application also
+  attempts to rotate the orientation, it can result in strange behavior. In addition, if your
+  application uses the accelerometer to detect shaking and you do not want to rotate the 
+  orientation, then you should lock the current orientation with 
+  <a href="{@docRoot}guide/topics/manifest/activity-element.html#screen">android:screenOrientation</a>.
+  </li>
+</ul>
+
+<p>Please read our blog post on <a 
+href="http://android-developers.blogspot.com/2009/04/future-proofing-your-apps.html">Future-Proofing
+Your Apps</a> for more information on the issues mentioned above.</p>
+
+<p>For information
+about other changes made to Android 1.5, refer to the following documents:</p>
 <ul>
   <li><a href="{@docRoot}sdk/api_diff/3/changes.html">Android 1.5 API Differences</a></li>
-  <li><a href="{@docRoot}sdk/android-1.5.html#api-changes">Android 1.5 Version Notes</a></li>
- <!-- <li><a href="">TODO: LINK TO DAN'S POST ON FORWARD COMPATIBILITY &raquo;</a></li>  -->
+  <li><a href="{@docRoot}sdk/android-1.5.html#api-changes">Android 1.5 Version Notes</a></li> 
   <li><a 
 href="http://android-developers.blogspot.com/2009/04/ui-framework-changes-in-android-15.html">UI 
 framework changes in Android 1.5 &raquo;</a></li>