android_frameworks_base/docs/html/guide/publishing/versioning.jd

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>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.html">The Manifest 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 &mdash; including other applications that you publish as
a suite &mdash; 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 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. </p>

<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> &mdash; 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> &mdash; 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
&lt;major&gt;.&lt;minor&gt;.&lt;point&gt; 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>&lt;manifest&gt;</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>&lt;manifest&gt;</code> element. </p>

<pre>
&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;manifest xmlns:android="http://schemas.android.com/apk/res/android"
      package="com.example.package.name"
      android:versionCode="2"
      android:versionName="1.1"&gt;
    &lt;application android:icon="@drawable/icon" android:label="@string/app_name"&gt;
        ...
    &lt;/application&gt;
&lt;/manifest&gt;
</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>

<p>If your application requires a specific minimum version of the Android
platform, you can also specify that in the manifest file: </p>

<ul>
<li><code>android:minSdkVersion</code> &mdash; 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>&lt;uses-sdk&gt;</code> element as a child of
<code>&lt;manifest&gt;</code>, then define the
<code>android:minSdkVersion</code> as an attribute. Currently, only one platform
version has been released for mobile devices &mdash; that version is "1". For
this reason, you do not need to define this attribute in your application and,
at this point, defining it is <em>not recommended</em>.</p>