Extension Versioning, Update and Compatibility

  • Revision slug: Extension_Versioning,_Update_and_Compatibility
  • Revision title: Extension Versioning, Update and Compatibility
  • Revision id: 17843
  • Created:
  • Creator: Mossop
  • Is current revision? No
  • Comment /* Custom Update RDF Format */

Revision Content

{{template.NeedsTechnicalReview()}}

Parts of this document are outdated and not apply to Firefox 1.5. Please help update them if you can.

This document is <span style="color: red">'''PRELIMINARY'''</span> - that is, it is not final and not everything here has been implemented. As soon as it is, this notice will be removed.


Firefox Versioning

In Firefox 1.5 this format has been replaced by the Toolkit version format

The Firefox Version Format (FVF) is:

major.minor.release.build[+]

Every field after major is optional, so 2.0, 2.5.1 and 7 are all valid version numbers, as is 5.0.0.2004072315.

Firefox and all Extensions and Themes that work with Firefox must be versioned in this way in order for compatibility checking and Update to work.

If you are not versioning this way now, start now. Versions like "2.0b" or "4.2 Preview" are not valid. If you want to display any additional information, use the em:name property.

How Firefox Determines Compatibility

Firefox uses the pref app.extensions.version to determine Extension compatibility for this release. When an Extension is installed, Firefox makes sure that app.extensions.version lies within the range set up by the Extension's install.rdf file using minVersion and maxVersion. If app.extensions.version is less than minVersion, a newer version of Firefox is required to install the Extension, if it is greater than maxVersion, Firefox is too new to install the extension.

If this basic compatibility check fails, Firefox will then attempt to "phone home" and obtain newer compatibility information for the Extension. If the Extension's install.rdf file specifies an update RDF file, this will be loaded and newer information discovered there (see below for format). If none is supplied, Firefox will check the generic update service running on addons.mozilla.org, and if the Extension is hosted there and has newer compatibility information it will be read and the local information updated.

If all of these methods fail, Firefox will show a message to the user saying that the Extension is incompatible and cannot be installed.

app.extensions.version

app.extensions.version is not used in Firefox 1.5.

The app.extensions.version pref will be incremented every time there are changes that might break extension authors, or every minor release, i.e. 0.9, 1.0, 1.1, etc. If a point release contains changes (heaven forbid) that might break extensions, we'll rev it then too. Every time we rev this pref, we will publically announce our intent to do so.

In most cases, this pref will stay the same between minor versions. For example, Firefox 1.1 ships, with app.extensions.version set to "1.1". Hypothetical security firedrills cause 1.1.1 and 1.1.2 releases, but both of these follow-ons still have app.extensions.version set to "1.1" - since there are no changes in the subminor releases that cause extension incompatibility, we don't want to break Extensions compatible with 1.1.

Footnote: Application Updates

In Firefox 0.9, Firefox used a single pref app.version to determine extension compatibility as described above and to use when comparing against newer available versions of Firefox. This caused some problems when the 0.9.1 release came out, because we held app.version at 0.9 to prevent breaking Extensions, but because we did so we ended up causing spurious update notifications appearing in people's clients because the Application software update file on update.mozilla.org (now aus.mozilla.org) kept broadcasting there was a newer version (0.9.1) available. So to prevent this from 1.0RC1 onwards app.version is used strictly for Application versioning only (and it is reved every subminor release) - app.extensions.version is now the pref used for Extensions versioning.

Power Tip: Installing Extensions You Know Are Compatible

This is only for people who know what they're doing. To install an Extension that is incompatible with the build you're using, open about:config and type app.extensions.version - and set the value of this pref to a version number that is compatible with the Extension. Now try installing the Extension. For safety's sake, reset the pref to its default value (Right click on the pref in about:config and choose "Reset Pref") so that you don't inadvertedly install incompatible Extensions at a later point. Firefox allows Extension sites to see what Extension version it is running with, so if you change this and forget to reset it then browse to an Extension site, you may install incompatible Extensions that mess up your browser.

If you mess things up doing this read the next section about using the Safe Mode to recover.

IMPORTANT: Recovering From Bad Extensions

In the Program Group the Firefox installer created in your Start menu you will find an item called, "Firefox (Safe Mode)" - if you run into problems, such as the browser not starting, performance being degraded, etc, try running by using this shortcut instead of your usual one, if things improve try uninstalling the last Extension(s) you installed.

If you did not install the Start Menu Program Group, or you're on Linux, start Firefox with the -safe-mode command line switch:

./firefox -safe-mode

Mac OS X users should do the following:

cd Firefox.app/Contents/MacOS
./firefox-bin -safe-mode

When run in Safe Mode, Firefox disables all Extensions and reverts to the Default Theme.

Automatic Extension Update Checking

Firefox periodically checks for updates not only to itself, but to your installed Extensions and Themes. If your Extension specified a custom update RDF file in its install.rdf manifest, then this will be checked, if not, Firefox will try and look for updates to it on addons.mozilla.org. If Firefox discovers a newer version available for any of your Extensions/Themes, it will display an indicator in the lower right corner of the browser window. You can also check manually by double clicking this indicator, or clicking the "Check Now" button in the Advanced section of Tools, Options.

If Firefox finds that minVersion and maxVersion have changed remotely for the same version of an Extension that you have installed, it will apply these changes into your local Extensions datasource to ensure ongoing compatibility when you update Firefox to a newer version. For rationale see the "Updating maxVersion" section below.

Choosing minVersion and maxVersion

You should set minVersion to the minimum version you want to support and test your extension with. There is no shame in this being the latest version of Firefox. If you do not plan on testing your Extension with a given version, minVersion must be set to the newest version you are willing to test with. You should never set maxVersion greater than the current Firefox release. You do not know what we're planning to do with the app in the future, and so you cannot reliably say that your Extension will be compatible. Mozilla's API set is not completely frozen, and parts of the Browser front end where you integrate UI with overlays may change. As usual, the more you rely on the browser and its unfrozen APIs to behave a certain way, the more likely you are to be broken in an update. It's fine for you to do this, you just need to appreciate that work will be required to update to support a newer version.

For this reason, addons.mozilla.org will not accept Extensions with maxVersion set to a version newer than the newest Firefox release.

Updating maxVersion

Say you create FooExtension 2.2, the long awaited update to critically acclaimed FooExtension 2.1. You're interested in supporting it with Firefox 0.9 only, so you set minVersion and maxVersion to 0.9 to support the single version.

Now suppose Firefox 1.0 comes out. You have a lot of users using FooExtension 2.2 on 0.9, and you suppose many of those users will upgrade to Firefox 1.0, but when that happens they'll all find their treasured FooExtension 2.2 will no longer work, right? Not necessarily. Assuming you don't need to make any changes to FooExtension 2.2 to make it work with 1.0 (this can be a pretty big assumption, and you should not assume - you should test, when you assume you make an ASS out of U and ME. ha ha.) - you can update your maxVersion to include 1.0, either on addons.mozilla.org through the UI if you're hosted there, or via your update RDF file (see format below). The next time Firefox checks for updates, it will apply any remote changes to the maxVersion into its local datasource so that functionality is preserved.

Supporting Multiple Versions

Suppose all of the previous is true, but at or around the same time you release FooExtension 2.3. FooExtension 2.3 is where your development effort is focused, and it is the one you intend to support from Firefox 1.0 onward - Firefox 1.0 might be the last release supported FooExtension 2.2, but you want your FooExtension 2.2 users to be able to upgrade to Firefox 1.0 and still use 2.2, if they have it.

If your Extension is hosted on addons.mozilla.org, you can store multiple versions of the same Extension in the database and you'll be fine because the automatic update service will take care of the details. If you're using a Custom update RDF file, you can add update info for several versions of a single Extension to the file in the format described below.

Custom Update RDF Format

This is only applicable if you're using the custom RDF system and not the generic system provided by addons.mozilla.org. To use the generic system provided by addons.mozilla.org you need to be hosted there.

<RDF:RDF xmlns:RDF="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
         xmlns:em="http://www.mozilla.org/2004/em-rdf#">

  <RDF:Description about="urn:mozilla:extension:{8be6949b-76b9-4da7-b453-b5f69a11c76e}">
    <em:updates>
      <!-- This is a list of all available updates. They must have unique
              URIs, per RDF Grammar rules, I've tacked the version number onto
              the end to differentiate versions -->
      <RDF:Seq>
        <RDF:li resource="urn:mozilla:extension:{8be6949b-76b9-4da7-b453-b5f69a11c76e}:2.2"/>
        <RDF:li resource="urn:mozilla:extension:{8be6949b-76b9-4da7-b453-b5f69a11c76e}:2.3"/>
      </RDF:Seq>
    </em:updates>

    <!-- Firefox 0.9 did not support the above RDF grammar, only the following
            two simple properties, so we also provide them here for people
            upgrading from Firefox 0.9. Note that we've used the larger of the two
            updates here, since Firefox 0.9 was not smart enough to have any of the
            logic to patch its Extensions datasource with information about existing
            Extensions that are also compatible with newer versions of
            the app. -->
    <em:version>2.3</em:version>
    <em:updateLink>http://www.mysite.com/fooextension2.3.xpi</em:updateLink>
  </RDF:Description>

  <!-- This Description describes an available update to version 2.2 of
          FooExtension - it defines a new maxVersion for the Firefox
          targetApplication (format of the targetApplication object is the
          same as for the install.rdf file, with the exception of the
          em:updateLink property, which contains a URL to the updated XPI) -->
  <RDF:Description about="urn:mozilla:extension:{8be6949b-76b9-4da7-b453-b5f69a11c76e}:2.2">
    <em:version>2.2</em:version>
    <em:targetApplication>
      <Description>
        <em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id>
        <em:minVersion>0.9</em:minVersion>
        <em:maxVersion>1.0</em:maxVersion>
        <em:updateLink>http://www.mysite.com/fooextension2.2.xpi</em:updateLink>
      </Description>
    </em:targetApplication>
  </RDF:Description>

  <!-- This Description describes an available update to version 2.3 of
          FooExtension - (format of the targetApplication object is the
          same as for the install.rdf file, with the exception of the
          em:updateLink property, which contains a URL to the updated XPI) -->
  <RDF:Description about="urn:mozilla:extension:{8be6949b-76b9-4da7-b453-b5f69a11c76e}:2.3">
    <em:version>2.3</em:version>
    <em:targetApplication>
      <Description>
        <em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id>
        <em:minVersion>1.0</em:minVersion>
        <em:maxVersion>1.0</em:maxVersion>
        <em:updateLink>http://www.mysite.com/fooextension2.3.xpi</em:updateLink>
      </Description>
    </em:targetApplication>
  </RDF:Description>

</RDF:RDF>

How Firefox Determines what Update to Offer

There are several events that cause Firefox to check for updates:

  1. User generated events (user double clicks on status bar indicator, clicks "Check Now" in Options, selects an Extension or Theme and clicks "Update", etc)
  2. Background events (Firefox's 24 hour update check timer)
  3. Mismatch events (A new version of Firefox is installed, and Firefox has to check for updates to determine if newer versions of incompatible Extensions are available).

Depending on the type of event, Firefox may be interested in seeing the newest version of a given Extension, or only in updating the local datasource with more up to date min/maxVersion info. Here's a breakdown.

For (1) - User Generated events, Firefox checks the addons.mozilla.org update service or the custom RDF file for each Extension first to see if the minVersion/maxVersion metadata is up to date. It updates this metadata silently. Then it checks to see if there really is a newer version available - and shows UI that presents these newer versions to give users a chance to upgrade.

For (2) - Background events, Firefox does basically the same as for (1).

For (3) - Firefox checks for updates, but does not present UI if compatibility is satisfied by simply updating minVersion/maxVersion. i.e. in the FooExtension example given, if a Firefox 0.9 user moves to 1.0, the first time he or she starts 1.0, Firefox will check the custom RDF file and silently patch the compatibility info for the installed FooExtension 2.2, and not show the "Incompatible Extensions" UI presenting 2.3 - since an upgrade to 2.3 is not strictly required for the user to update. The emphasis here is on presenting a simplified user experience. Users will learn about 2.3 when Firefox does a subsequent update check.

What Does All This Mean?

What this means is that if your extension is compatible with a newer version of Firefox and the version number of that compatible version has not changed, when the newer version of Firefox comes out, all you need to do is update your listing in addons.mozilla.org or your custom RDF file to indicate this compatibility change, and existing and new users of that version of your extension will be able to use it in the newer version of Firefox. Existing users because Firefox will check with the update service/RDF either in the background or when they upgrade and patch their local datasource, and new users because when they install the XPI and Firefox deems it incompatible based on the information in the install.rdf file, Firefox will check with the update service/RDF at that time to determine whether or not it really is compatible.

This implies that you do not need to release an updated XPI with an ammended install.rdf file as long as you keep the remote metadata up to date, although you may like to anyway if you believe there's a chance users will want to install that XPI when they don't have an internet connection (since clearly the update checking will not work in that case).

Themes

Almost everywhere I say "Extensions" I could also say "Themes" - for brevity I only say the former.

Thunderbird

All of this applies to Thunderbird too.


Original Document Information

  • Author(s): Ben Goodger
  • Original Document: Extension Versioning
  • Last Updated Date: December 16, 2004
  • Copyright Information: Copyright (C) Ben Goodger

Revision Source

<p>
</p><p>{{template.NeedsTechnicalReview()}}
</p>
<div class="note">Parts of this document are outdated and not apply to Firefox 1.5. Please help update them if you can.</div>
<p><span class="comment">This document is &lt;span style="color: red"&gt;'''PRELIMINARY'''&lt;/span&gt; - that is, it is not final and not everything here has been implemented. As soon as it is, this notice will be removed.</span>
</p><p><br>
</p>
<h2 name="Firefox_Versioning">Firefox Versioning</h2>
<div class="note">In Firefox 1.5 this format has been replaced by the <a href="en/Toolkit_version_format">Toolkit version format</a></div>
<p>The Firefox Version Format (FVF) is:
</p>
<pre class="eval">major.minor.release.build[+]
</pre>
<p>Every field after major is optional, so 2.0, 2.5.1 and 7 are all valid version
numbers, as is 5.0.0.2004072315.
</p><p><b>Firefox and all Extensions and Themes that work with Firefox must be versioned in this way in order for compatibility checking and Update to work.</b>
</p><p>If you are not versioning this way now, <b>start now</b>. Versions
like "2.0b" or "4.2 Preview" are <i>not valid</i>. If you want to display any
additional information, use the <code>em:name</code> property.
</p>
<h2 name="How_Firefox_Determines_Compatibility">How Firefox Determines Compatibility</h2>
<p>Firefox uses the pref <code>app.extensions.version</code> to determine
Extension compatibility for this release. When an Extension is installed,
Firefox makes sure that <code>app.extensions.version</code> lies within the
range set up by the Extension's install.rdf file using minVersion and
maxVersion. If <code>app.extensions.version</code>
is less than minVersion, a newer version of Firefox is required to install the
Extension, if it is greater than maxVersion, Firefox is too new to install the
extension.
</p><p>If this basic compatibility check fails, Firefox will then attempt to "phone
home" and obtain newer compatibility information for the Extension. If the
Extension's install.rdf file specifies an update RDF file, this will be loaded
and newer information discovered there (see below for format). If none is
supplied, Firefox will check the generic update service running on
addons.mozilla.org, and if the Extension is hosted there and has newer
compatibility information it will be read and the local information updated.
</p><p>If all of these methods fail, Firefox will show a message to the user saying
that the Extension is incompatible and cannot be installed.
</p>
<h3 name="app.extensions.version">app.extensions.version</h3>
<div class="note">app.extensions.version is not used in Firefox 1.5.</div>
<p>The app.extensions.version pref will be incremented every time there are
changes that might break extension authors, or every minor release, i.e. 0.9,
1.0, 1.1, etc. If a point release contains changes (heaven forbid) that might
break extensions, we'll rev it then too. Every time we rev this pref, we will
publically announce our intent to do so.
</p><p>In most cases, this pref will stay the same between minor versions. For
example, Firefox 1.1 ships, with app.extensions.version set to "1.1".
Hypothetical security firedrills cause 1.1.1 and 1.1.2 releases, but both of
these follow-ons still have app.extensions.version set to "1.1" - since there
are no changes in the subminor releases that cause extension incompatibility,
we don't want to break Extensions compatible with 1.1.
</p>
<h3 name="Footnote:_Application_Updates">Footnote: Application Updates</h3>
<p>In Firefox 0.9, Firefox used a single pref <code>app.version</code> to
determine extension compatibility as described above <i>and</i> to use when
comparing against newer available versions of Firefox. This caused some
problems when the 0.9.1 release came out, because we held <code>app.version</code>
at 0.9 to prevent breaking Extensions, but because we did so we ended up
causing spurious update notifications appearing in people's clients because the
Application software update file on update.mozilla.org (now aus.mozilla.org)
kept broadcasting there
was a newer version (0.9.1) available. So to prevent this from 1.0RC1 onwards
<code>app.version</code> is used strictly for Application versioning <i>only</i> (and
it is reved every subminor release) - <code>app.extensions.version</code> is
now the pref used for Extensions versioning.
</p>
<h3 name="Power_Tip:_Installing_Extensions_You_Know_Are_Compatible">Power Tip: Installing Extensions You Know Are Compatible</h3>
<p>This is <b>only</b> for people who <i>know what they're doing</i>.
To install an Extension that is incompatible with the build you're using, open
<code>about:config</code> and type <code>app.extensions.version</code>
- and set the value of this pref to a version number that is compatible with
the Extension. Now try installing the Extension. For safety's sake, reset the
pref to its default value (Right click on the pref in about:config and choose
"Reset Pref") so that you don't inadvertedly install incompatible Extensions at
a later point. Firefox allows Extension sites to see what Extension version it
is running with, so if you change this and forget to reset it then browse to an
Extension site, you may install incompatible Extensions that mess up your
browser.
</p><p><b>If you mess things up doing this</b> read the next section about
using the Safe Mode to recover.
</p>
<h3 name="IMPORTANT:_Recovering_From_Bad_Extensions">IMPORTANT: Recovering From Bad Extensions</h3>
<p>In the Program Group the Firefox installer created in your Start menu you will
find an item called, "Firefox (Safe Mode)" - if you run into problems, such as
the browser not starting, performance being degraded, etc, try running by using
this shortcut instead of your usual one, if things improve try uninstalling the
last Extension(s) you installed.
</p><p>If you did not install the Start Menu Program Group, or you're on Linux, start
Firefox with the <code>-safe-mode</code> command line switch:
</p>
<pre class="eval">./firefox -safe-mode
</pre>
<p>Mac OS X users should do the following:
</p>
<pre class="eval">cd Firefox.app/Contents/MacOS<br>./firefox-bin -safe-mode
</pre>
<p>When run in Safe Mode, Firefox disables all Extensions and reverts to the
Default Theme.
</p>
<h2 name="Automatic_Extension_Update_Checking">Automatic Extension Update Checking</h2>
<p>Firefox periodically checks for updates not only to itself, but to your
installed Extensions and Themes. If your Extension specified a custom update
RDF file in its install.rdf manifest, then this will be checked, if not,
Firefox will try and look for updates to it on addons.mozilla.org. If Firefox
discovers a newer version available for any of your Extensions/Themes, it will
display an indicator in the lower right corner of the browser window. You can
also check manually by double clicking this indicator, or clicking the "Check
Now" button in the Advanced section of Tools, Options.
</p><p>If Firefox finds that minVersion and maxVersion have changed remotely for the
same version of an Extension that you have installed, it will apply these
changes into your local Extensions datasource to ensure ongoing compatibility
when you update Firefox to a newer version. For rationale see the "Updating
maxVersion" section below.
</p>
<h2 name="Choosing_minVersion_and_maxVersion">Choosing minVersion and maxVersion</h2>
<p>You should set minVersion to the minimum version you want to support and test
your extension with. There is no shame in this being the latest version of
Firefox. <b>If you do not plan on testing your Extension with a given</b>
version, minVersion must be set to the newest version you are willing to test
with.<b> You should never set maxVersion greater than the current</b>
Firefox release. You do <b>not</b> know what we're planning to do
with the app in the future, and so you cannot reliably say that your Extension
will be compatible. Mozilla's API set is not completely frozen, and parts of
the Browser front end where you integrate UI with overlays may change. As
usual, the more you rely on the <i>browser</i>
and its unfrozen APIs to behave a certain way, the more likely you are to be
broken in an update. It's fine for you to do this, you just need to appreciate
that work will be required to update to support a newer version.
</p><p>For this reason, addons.mozilla.org will not accept Extensions with maxVersion
set to a version newer than the newest Firefox release.
</p>
<h2 name="Updating_maxVersion">Updating maxVersion</h2>
<p>Say you create FooExtension 2.2, the long awaited update to critically
acclaimed FooExtension 2.1. You're interested in supporting it with Firefox 0.9
only, so you set minVersion and maxVersion to 0.9 to support the single
version.
</p><p>Now suppose Firefox 1.0 comes out. You have a lot of users using FooExtension
2.2 on 0.9, and you suppose many of those users will upgrade to Firefox 1.0,
but when that happens they'll all find their treasured FooExtension 2.2 will no
longer work, right? Not necessarily. Assuming you don't need to make any
changes to FooExtension 2.2 to make it work with 1.0 (this can be a pretty big
assumption, and you should not assume - you should test, when you assume you
make an ASS out of U and ME. ha ha.) - you can update your maxVersion to
include 1.0, either on addons.mozilla.org through the UI if you're hosted
there, or via your update RDF file (see format below). The next time Firefox
checks for updates, it will apply any remote changes to the maxVersion into its
local datasource so that functionality is preserved.
</p>
<h2 name="Supporting_Multiple_Versions">Supporting Multiple Versions</h2>
<p>Suppose all of the previous is true, but at or around the same time you
release FooExtension 2.3. FooExtension 2.3 is where your development effort is
focused, and it is the one you intend to support from Firefox 1.0 onward -
Firefox 1.0 might be the last release supported FooExtension 2.2, <i>but</i>
you want your FooExtension 2.2 users to be able to upgrade to Firefox 1.0 and
still use 2.2, if they have it.
</p><p>If your Extension is hosted on addons.mozilla.org, you can store multiple
versions of the same Extension in the database and you'll be fine because the
automatic update service will take care of the details. If you're using a
Custom update RDF file, you can add update info for several versions of a
single Extension to the file in the format described below.
</p>
<h2 name="Custom_Update_RDF_Format">Custom Update RDF Format</h2>
<p>This is only applicable if you're using the custom RDF system and not the
generic system provided by addons.mozilla.org. To use the generic system
provided by addons.mozilla.org you need to be hosted there.
</p>
<pre class="eval">&lt;RDF:RDF xmlns:RDF="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
         xmlns:em="http://www.mozilla.org/2004/em-rdf#"&gt;

  &lt;RDF:Description about="urn:mozilla:extension:{8be6949b-76b9-4da7-b453-b5f69a11c76e}"&gt;
    &lt;em:updates&gt;
      &lt;!-- This is a list of all available updates. They must have unique
              URIs, per RDF Grammar rules, I've tacked the version number onto
              the end to differentiate versions --&gt;
      &lt;RDF:Seq&gt;
        &lt;RDF:li resource="urn:mozilla:extension:{8be6949b-76b9-4da7-b453-b5f69a11c76e}:2.2"/&gt;
        &lt;RDF:li resource="urn:mozilla:extension:{8be6949b-76b9-4da7-b453-b5f69a11c76e}:2.3"/&gt;
      &lt;/RDF:Seq&gt;
    &lt;/em:updates&gt;

    &lt;!-- Firefox 0.9 did not support the above RDF grammar, only the following
            two simple properties, so we also provide them here for people
            upgrading from Firefox 0.9. Note that we've used the larger of the two
            updates here, since Firefox 0.9 was not smart enough to have any of the
            logic to patch its Extensions datasource with information about existing
            Extensions that are <i>also</i> compatible with newer versions of
            the app. --&gt;
    &lt;em:version&gt;2.3&lt;/em:version&gt;
    &lt;em:updateLink&gt;http://www.mysite.com/fooextension2.3.xpi&lt;/em:updateLink&gt;
  &lt;/RDF:Description&gt;

  &lt;!-- This Description describes an available update to version 2.2 of
          FooExtension - it defines a new maxVersion for the Firefox
          targetApplication (format of the targetApplication object is the
          same as for the install.rdf file, with the exception of the
          em:updateLink property, which contains a URL to the updated XPI) --&gt;
  &lt;RDF:Description about="urn:mozilla:extension:{8be6949b-76b9-4da7-b453-b5f69a11c76e}:2.2"&gt;
    &lt;em:version&gt;2.2&lt;/em:version&gt;
    &lt;em:targetApplication&gt;
      &lt;Description&gt;
        &lt;em:id&gt;{ec8030f7-c20a-464f-9b0e-13a3a9e97384}&lt;/em:id&gt;
        &lt;em:minVersion&gt;0.9&lt;/em:minVersion&gt;
        &lt;em:maxVersion&gt;1.0&lt;/em:maxVersion&gt;
        &lt;em:updateLink&gt;http://www.mysite.com/fooextension2.2.xpi&lt;/em:updateLink&gt;
      &lt;/Description&gt;
    &lt;/em:targetApplication&gt;
  &lt;/RDF:Description&gt;

  &lt;!-- This Description describes an available update to version 2.3 of
          FooExtension - (format of the targetApplication object is the
          same as for the install.rdf file, with the exception of the
          em:updateLink property, which contains a URL to the updated XPI) --&gt;
  &lt;RDF:Description about="urn:mozilla:extension:{8be6949b-76b9-4da7-b453-b5f69a11c76e}:2.3"&gt;
    &lt;em:version&gt;2.3&lt;/em:version&gt;
    &lt;em:targetApplication&gt;
      &lt;Description&gt;
        &lt;em:id&gt;{ec8030f7-c20a-464f-9b0e-13a3a9e97384}&lt;/em:id&gt;
        &lt;em:minVersion&gt;1.0&lt;/em:minVersion&gt;
        &lt;em:maxVersion&gt;1.0&lt;/em:maxVersion&gt;
        &lt;em:updateLink&gt;http://www.mysite.com/fooextension2.3.xpi&lt;/em:updateLink&gt;
      &lt;/Description&gt;
    &lt;/em:targetApplication&gt;
  &lt;/RDF:Description&gt;

&lt;/RDF:RDF&gt;
</pre>
<h2 name="How_Firefox_Determines_what_Update_to_Offer">How Firefox Determines what Update to Offer</h2>
<p>There are several events that cause Firefox to check for updates:
</p>
<ol><li> User generated events (user double clicks on status bar indicator, clicks "Check Now" in Options, selects an Extension or Theme and clicks "Update", etc)
</li><li> Background events (Firefox's 24 hour update check timer)
</li><li> Mismatch events (A new version of Firefox is installed, and Firefox has to check for updates to determine if newer versions of incompatible Extensions are available).
</li></ol>
<p>Depending on the type of event, Firefox may be interested in seeing the newest
version of a given Extension, or only in updating the local datasource with
more up to date min/maxVersion info. Here's a breakdown.
</p><p>For (1) - User Generated events, Firefox checks the addons.mozilla.org update
service or the custom RDF file for each Extension first to see if the
minVersion/maxVersion metadata is up to date. It updates this metadata
silently. Then it checks to see if there really is a newer version available -
and shows UI that presents these newer versions to give users a chance to
upgrade.
</p><p>For (2) - Background events, Firefox does basically the same as for (1).
</p><p>For (3) - Firefox checks for updates, but does not present UI if compatibility
is satisfied by simply updating minVersion/maxVersion. i.e. in the FooExtension
example given, if a Firefox 0.9 user moves to 1.0, the first time he or she
starts 1.0, Firefox will check the custom RDF file and silently patch the
compatibility info for the installed FooExtension 2.2, and <i>not</i> show
the "Incompatible Extensions" UI presenting 2.3 - since an upgrade to 2.3 is <i>not</i>
strictly required<i> for the user to update. The emphasis here is on</i>
presenting a simplified user experience. Users will learn about 2.3 when
Firefox does a subsequent update check.
</p>
<h2 name="What_Does_All_This_Mean.3F">What Does All This Mean?</h2>
<p>What this means is that <i>if your extension is compatible with a newer version</i>
of Firefox<i> and the version number of that compatible version has not changed, when the</i>
newer version of Firefox comes out, all you need to do is update your listing
in addons.mozilla.org or your custom RDF file to indicate this compatibility
change, and existing and new users of that version of your extension will be
able to use it in the newer version of Firefox. Existing users because Firefox
will check with the update service/RDF either in the background or when they
upgrade and patch their local datasource, and new users because when they
install the XPI and Firefox deems it incompatible based on the information in
the install.rdf file, Firefox will check with the update service/RDF at that
time to determine whether or not it really is compatible.
</p><p>This implies that you do <i>not</i> need to release an updated XPI with an
ammended install.rdf file as long as you keep the remote metadata up to date,
although you may like to anyway if you believe there's a chance users will want
to install that XPI when they don't have an internet connection (since clearly
the update checking will not work in that case).
</p>
<h2 name="Themes">Themes</h2>
<p>Almost everywhere I say "Extensions" I could also say "Themes" - for brevity I
only say the former.
</p>
<h2 name="Thunderbird">Thunderbird</h2>
<p>All of this applies to Thunderbird too.
</p><p><br>
</p>
<div class="originaldocinfo">
<h2 name="Original_Document_Information">Original Document Information</h2>
<ul><li> Author(s): Ben Goodger
</li><li> Original Document: <a class="external" href="http://www.mozilla.org/projects/firefox/extensions/update.html">Extension Versioning</a>
</li><li> Last Updated Date: December 16, 2004
</li><li> Copyright Information: Copyright (C) Ben Goodger
</li></ul>
</div>
Revert to this revision