Bug 723584 - Document SDK compatibility with Firefox versions; r=@warner

(cherry picked from commit 33e63ab)

doc/dev-guide-source/addon-development/firefox-compatibility.md

@@ -0,0 +1,100 @@
+
+# Firefox Compatibility #
+
+One of the promises the SDK makes is to maintain compatibility for its
+["supported" or "high-level" APIs](packages/addon-kit/addon-kit.html):
+meaning that code written against them will not need to change as new
+versions of Firefox are released.
+
+This ties the SDK release cycle into the Firefox release cycle because
+the SDK must absorb any changes made to Firefox APIs. The SDK
+and Firefox both release every 6 weeks, and the releases are precisely
+staggered: so the SDK releases three weeks before Firefox. Each SDK
+release is tested against, and marked as compatible with, two
+versions of Firefox:
+
+* the currently shipping Firefox version at the time the SDK is released
+* the Beta Firefox version at the time the SDK is released - which,
+because SDK and Firefox releases are staggered, will become the
+currently shipping Firefox three week later
+
+Add-ons built using a particular version of the SDK are marked
+as being compatible with those two versions of Firefox, meaning
+that in the
+[`targetApplication` field of the add-on's install.rdf](https://developer.mozilla.org/en/Install.rdf#targetApplication):
+
+* the `minVersion` is set to the currently shipping Firefox
+* the `maxVersion` is set to the current Firefox Beta
+
+See the
+[SDK Release Schedule](https://wiki.mozilla.org/Jetpack/SDK_2012_Release_Schedule)
+for the list of all SDK releases scheduled for 2012, along with the Firefox
+versions they are compatible with.
+
+## "Compatible By Default" ##
+
+<span class="aside">There are exceptions to the "compatible by default" rule:
+add-ons with binary XPCOM components, add-ons that have their compatibility
+set to less than Firefox 4, and add-ons that are repeatedly reported as
+incompatible, which are added to a compatibility override list.
+</span>
+
+From Firefox 10 onwards, Firefox treats add-ons as
+"compatible by default": that is, even if the Firefox installing the
+add-on is not inside the range defined in `targetApplication`,
+Firefox will happily install it.
+
+For example, although an add-on developed using version 1.6 of the SDK will be
+marked as compatible with only versions 11 and 12 of Firefox, users of
+Firefox 10 will still be able to install it.
+
+But before version 10, Firefox assumed that add-ons were incompatible unless
+they were marked as compatible in the `targetApplication` field: so an add-on
+developed using SDK 1.6 will not install on Firefox 9.
+
+## Changing minVersion and maxVersion Values ##
+
+The `minVersion` and `maxVersion` values that are written into add-ons
+generated with the SDK are taken from the template file found at:
+
+<pre>
+python-lib/cuddlefish/app-extension/install.rdf
+</pre>
+
+If you need to create add-ons which are compatible with a wider range of
+Firefox releases, you can edit this file to change the
+`minVersion...maxVersion` range.
+
+Obviously, you should be careful to test the resulting add-on on the extra
+versions of Firefox you are including, because the version of the SDK you
+are using will not have been tested against them.
+
+## Repacking Add-ons ##
+
+Suppose you create an add-on using version 1.6 of the SDK, and upload it to
+[https://addons.mozilla.org/](https://addons.mozilla.org/). It's compatible
+with versions 11 and 12 of Firefox, and indicates that in its
+`minVersion...maxVersion` range.
+
+Now Firefox 13 is released. Suppose Firefox 13 does not change any of the
+APIs used by version 1.6 of the SDK. In this case the add-on will still
+work with Firefox 13.
+
+But if Firefox 13 makes some incompatible changes, then the add-on will
+no longer work. In this case, we'll notify developers, who will need to:
+
+* download and install a new version of the SDK
+* rebuild their add-on using this version of the SDK
+* update their XPI on [https://addons.mozilla.org/](https://addons.mozilla.org/)
+with the new version.
+
+If you created the add-on using the [Add-on Builder](https://builder.addons.mozilla.org/)
+rather than locally using the SDK, then it will be repacked automatically
+and you don't have to do this.
+
+### Future Plans ###
+
+The reason add-ons need to be repacked when Firefox changes is that the
+SDK modules used by an add-on are packaged as part of the add-on, rather
+than part of Firefox. In the future we plan to start shipping SDK modules
+in Firefox, and repacking will not be needed any more.

doc/dev-guide-source/addon-development/guides.md

@@ -20,3 +20,5 @@ What the program ID is and why it matters to your add-on.
 ### [Module Search](dev-guide/addon-development/module-search.html) ###
 How the `require()` function finds the module you asked for.
 
+### [Firefox Compatibility](dev-guide/addon-development/firefox-compatibility.html) ###
+How SDK versions map to Firefox versions.

doc/dev-guide-source/addon-development/installation.md

@@ -11,13 +11,17 @@ To develop with the Add-on SDK, you'll need:
 * [Python](http://www.python.org/) 2.5 or 2.6. Note that versions 3.0 and 3.1
   of Python are not supported. Make sure that Python is in your path.
 
-* Firefox version 4.0 or later.
+* A [compatible version of Firefox](dev-guide/addon-development/firefox-compatibility.html).
+That's either: the version of Firefox shipping at the time the SDK shipped,
+or the Beta version of Firefox at the time the SDK shipped. See the
+[SDK Release Schedule](https://wiki.mozilla.org/Jetpack/SDK_2012_Release_Schedule)
+to map SDK releases to Firefox releases.
 
-You can obtain the latest stable version of the SDK as a
+* The SDK itself: you can obtain the latest stable version of the SDK as a
 [tarball](https://ftp.mozilla.org/pub/mozilla.org/labs/jetpack/jetpack-sdk-latest.tar.gz)
 or a [zip file](https://ftp.mozilla.org/pub/mozilla.org/labs/jetpack/jetpack-sdk-latest.zip).
-Alternatively, you can get the latest development version of the
-Add-on SDK from its [GitHub repository](https://github.com/mozilla/addon-sdk).
+Alternatively, you can get the latest development version from its
+[GitHub repository](https://github.com/mozilla/addon-sdk).
 
 ## Installation on Mac OS X / Linux ##
 

doc/static-files/base.html

@@ -123,6 +123,7 @@ <h3 class="sidebar-subsection-header"><a href="dev-guide/addon-development/guide
               </ul></li>
             <li><h4><a href="dev-guide/addon-development/program-id.html">The Program ID</a></h4></li>
             <li><h4><a href="dev-guide/addon-development/module-search.html">Module Search</a></h4></li>
+            <li><h4><a href="dev-guide/addon-development/firefox-compatibility.html">Firefox Compatibility</a></h4></li>
           </ul>
           </div>
         </div>