Extension Versioning, Update and Compatibility
or, How to Handle Firefox Version Upgrades
Ben Goodger, 07/20/2004
This document is Preliminary - 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
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
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 updates available 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 updates available 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:
- User generated events (user double clicks on status bar indicator, clicks "Check Now" in Options, selects an Extension or Theme and clicks "Update", etc)
- Background events (Firefox's 24 hour update check timer)
- 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.