docs: add info about manifest attributes that should not change

Change-Id: Ia58d855ccaa3348bc0a2f7a4b7847ec115c442e8

4 files changed, 28 insertions, 5 deletions

diff --git a/docs/html/guide/topics/manifest/activity-element.jd b/docs/html/guide/topics/manifest/activity-element.jd
index c910686..3486212 100644
--- a/docs/html/guide/topics/manifest/activity-element.jd
+++ b/docs/html/guide/topics/manifest/activity-element.jd
@@ -507,6 +507,10 @@ However, as a shorthand, if the first character of the name is a period
 package name specified in the 
 <code><a href="{@docRoot}guide/topics/manifest/manifest-element.html">&lt;manifest&gt;</a></code> 
 element.
+<p>Once you publish your application, you <a
+href="http://android-developers.blogspot.com/2011/06/things-that-cannot-change.html">should not
+change this name</a> (unless you've set <code><a
+href="#exported">android:exported</a>="false"</code>).</p>
 
 <p>
 There is no default.  The name must be specified.
diff --git a/docs/html/guide/topics/manifest/manifest-element.jd b/docs/html/guide/topics/manifest/manifest-element.jd
index 598e88f..d737a67 100644
--- a/docs/html/guide/topics/manifest/manifest-element.jd
+++ b/docs/html/guide/topics/manifest/manifest-element.jd
@@ -47,12 +47,15 @@ and specify {@code xlmns:android} and {@code package} attributes.</dd>
 to "{@code http://schemas.android.com/apk/res/android}".</dd>
 
 <dt><a name="package"></a>{@code package}</dt>
-<dd>A full Java package name for the application.  The name should 
+<dd>A full Java-language-style package name for the application.  The name should 
 be unique.  The name may contain uppercase or lowercase letters ('A'
 through 'Z'), numbers, and underscores ('_').  However, individual
-package name parts may only start with letters.  For example, applications
-published by Google could have names in the form
-<code>com.google.app.<i>application_name</i></code>.
+package name parts may only start with letters.
+
+<p>To avoid conflicts with other developers, you should use Internet domain ownership as the
+basis for your package names (in reverse). For example, applications published by Google start with
+<code>com.google</code>. You should also never use the <code>com.example</code> namespace when
+publishing your applications.</p>
 
   <p>
   The package name serves as a unique identifier for the application.
@@ -66,6 +69,12 @@ published by Google could have names in the form
   element's
   <code><a href="{@docRoot}guide/topics/manifest/activity-element.html#aff">taskAffinity</a></code> attribute).
   </p>
+
+  <p class="caution"><strong>Caution:</strong> Once you publish your application, you
+<strong>cannot change the package name</strong>. The package name defines your application's
+identity, so if you change it, then it is considered to be a different application and users of
+the previous version cannot update to the new version.</p>
+
 </dd>
 
 <dt><a name="uid"></a>{@code android:sharedUserId}</dt>
diff --git a/docs/html/guide/topics/manifest/receiver-element.jd b/docs/html/guide/topics/manifest/receiver-element.jd
index 7012c0f..8416c0c 100644
--- a/docs/html/guide/topics/manifest/receiver-element.jd
+++ b/docs/html/guide/topics/manifest/receiver-element.jd
@@ -122,6 +122,11 @@ as a shorthand, if the first character of the name is a period (for example,
 "{@code . ReportReceiver}"), it is appended to the package name specified in 
 the <code><a href="{@docRoot}guide/topics/manifest/manifest-element.html">&lt;manifest&gt;</a></code> element.  
 
+<p>Once you publish your application, you <a
+href="http://android-developers.blogspot.com/2011/06/things-that-cannot-change.html">should not
+change this name</a> (unless you've set <code><a
+href="#exported">android:exported</a>="false"</code>).</p>
+
 <p>
 There is no default.  The name must be specified.
 </p></dd>
diff --git a/docs/html/guide/topics/manifest/service-element.jd b/docs/html/guide/topics/manifest/service-element.jd
index d9a81b3..82d1f6a 100644
--- a/docs/html/guide/topics/manifest/service-element.jd
+++ b/docs/html/guide/topics/manifest/service-element.jd
@@ -6,7 +6,7 @@ parent.link=manifest-intro.html
 <dl class="xml">
 <dt>syntax:</dt>
 <dd><pre class="stx">&lt;service android:<a href="#enabled">enabled</a>=["true" | "false"]
-         android:<a href="#exported">exported[</a>="true" | "false"]
+         android:<a href="#exported">exported</a>=["true" | "false"]
          android:<a href="#icon">icon</a>="<i>drawable resource</i>"
          android:<a href="#label">label</a>="<i>string resource</i>"
          android:<a href="#nm">name</a>="<i>string</i>"
@@ -121,6 +121,11 @@ the first character of the name is a period (for example, "{@code .RoomService}"
 it is appended to the package name specified in the 
 <code><a href="{@docRoot}guide/topics/manifest/manifest-element.html">&lt;manifest&gt;</a></code> element.  
 
+<p>Once you publish your application, you <a
+href="http://android-developers.blogspot.com/2011/06/things-that-cannot-change.html">should not
+change this name</a> (unless you've set <code><a
+href="#exported">android:exported</a>="false"</code>).</p>
+
 <p>
 There is no default.  The name must be specified.
 </p></dd>