diff options
Diffstat (limited to 'docs/html/guide/publishing/versioning.jd')
| -rw-r--r-- | docs/html/guide/publishing/versioning.jd | 155 |
1 files changed, 155 insertions, 0 deletions
diff --git a/docs/html/guide/publishing/versioning.jd b/docs/html/guide/publishing/versioning.jd new file mode 100644 index 0000000..d0eafcd --- /dev/null +++ b/docs/html/guide/publishing/versioning.jd @@ -0,0 +1,155 @@ +page.title=Versioning Your Applications +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> + +<h2>Versioning quickview</h2> + +<ul> +<li>Your application <em>must</em> be versioned</a></li> +<li>You set the version in the application's manifest file</li> +<li>How you version your applications affects how users upgrade </li> +<li>Determine your versioning strategy early in the development process, including considerations for future releases.</li> +</ul> + +<h2>In this document</h2> + +<ol> +<li><a href="#appversion">Setting Application Version</a></li> +<li><a href="#minsdkversion">Specifying Minimum System API Version</a> +</ol> + + +<h2>See also</h2> + +<ol> +<li><a href="{@docRoot}guide/publishing/preparing.html">Preparing to Publish Your Application</a></li> +<li><a href="{@docRoot}guide/publishing/publishing.html#market">Publishing On Android Market</a></li> +<li><a href="{@docRoot}guide/topics/manifest/manifest-intro.html">The AndroidManifest.xml File</a></li> +</ol> + +</div> +</div> + +<p>Versioning is a critical component of your application upgrade/maintenance +strategy. </p> + +<ul> +<li>Users need to have specific information about the application version that +is installed on their devices and the upgrade versions available for +installation. </li> +<li>Other applications — including other applications that you publish as +a suite — need to query the system for your application's version, to +determine compatibility and identify dependencies.</li> +<li>Services through which you will publish your application(s) may also need to +query your application for its version, so that they can display the version to +users. A publishing service may also need to check the application version to +determine compatibility and establish upgrade/downgrade relationships.</li> +</ul> + +<p>The Android system itself <em>does not ever</em> check the application version +information for an application, such as to enforce restrictions on upgrades, +compatibility, and so on. Instead, only users or applications themselves are +responsible for enforcing any version restrictions for applications themselves. </p> + +<p>The Android system <em>does</em> check any system version compatibility expressed +by an application in its manifest, in the <code>minSdkVersion</code> attribute. This +allows an application to specify the minimum system API with which is compatible. +For more information see <a href="#minsdkversion">Specifying Minimum System API Version</a>. + +<h2 id="appversioning">Setting Application Version</h2> +<p>To define the version information for your application, you set attributes in +the application's manifest file. Two attributes are available, and you should +always define values for both of them: </p> + +<ul> +<li><code>android:versionCode</code> — An integer value that represents +the version of the application code, relative to other versions. + +<p>The value is an integer so that other applications can programatically +evaluate it, for example to check an upgrade or downgrade relationship. You can +set the value to any integer you want, however you should make sure that each +successive release of your application uses a greater value. The system does not +enforce this behavior, but increasing the value with successive releases is +normative. </p> + +<p>Typically, you would release the first version of your application with +versionCode set to 1, then monotonically increase the value with each release, +regardless whether the release constitutes a major or minor release. This means +that the <code>android:versionCode</code> value does not necessarily have a +strong resemblence to the application release version that is visible to the +user (see <code>android:versionName</code>, below). Applications and publishing +services should not display this version value to users.</p> +</li> +<li><code>android:versionName</code> — A string value that represents the +release version of the application code, as it should be shown to users. +<p>The value is a string so that you can describe the application version as a +<major>.<minor>.<point> string, or as any other type of +absolute or relative version identifier. </p> + +<p>As with <code>android:versionCode</code>, the system does not use this value +for any internal purpose, other than to enable applications to display it to +users. Publishing services may also extract the <code>android:versionName</code> +value for display to users.</p> +</li> +</ul> + +<p>You define both of these version attributes in the +<code><manifest></code> element of the manifest file. </p> + +<p>Here's an example manifest that shows the <code>android:versionCode</code> +and <code>android:versionName</code> attributes in the +<code><manifest></code> element. </p> + +<pre> +<?xml version="1.0" encoding="utf-8"?> +<manifest xmlns:android="http://schemas.android.com/apk/res/android" + package="com.example.package.name" + android:versionCode="2" + android:versionName="1.1"> + <application android:icon="@drawable/icon" android:label="@string/app_name"> + ... + </application> +</manifest> +</pre> + +<p>In this example, note that <code>android:versionCode</code> value indicates +that the current .apk contains the second release of the application code, which +corresponds to a minor follow-on release, as shown by the +<code>android:codeName</code> string. </p> + +<p>The Android framework provides an API to let applications query the system +for version information about your application. To obtain version information, +applications use the +{@link android.content.pm.PackageManager#getPackageInfo(java.lang.String, int)} +method of {@link android.content.pm.PackageManager PackageManager}. </p> + +<h2 id="minsdkversion">Specifying Minimum System API Version</h2> + +<p>If your application requires a specific minimum version of the Android +platform, you can specify that version as an API Level identifier +in the application's manifest file. Doing so ensures that your +application can only be installed on devices that +are running a compatible version of the Android system. </p> + +<p>To specify the minimum system version in the manifest, use this attribute: </p> + +<ul> +<li><code>android:minSdkVersion</code> — An integer value corresponding to +the code version of the Android platform. +<p>When preparing to install an application, the system checks the value of this +attribute and compares it to the system version. If the +<code>android:minSdkVersion</code> value is greater than the system version, the +system aborts the installation of the application. </p> + +<p>If you do not specify this attribute in your manifest, the system assumes +that your application is compatible with all platform versions.</p></li> +</ul> + +<p>To specify a minimum platform version for your application, add a +<code><uses-sdk></code> element as a child of +<code><manifest></code>, then define the +<code>android:minSdkVersion</code> as an attribute. </p> + +<p>For more information, also see the <a href="{@docRoot}sdk/android-1.1.html">Android System Image 1.1 Version Notes</a>.</p> |