Bundling Add-ons to Ship with Firefox

Why

Valid reasons to ship a feature as an add-on bundled with Firefox:

You want to reduce the barriers to contribution to your feature by reducing the amount of code that a developer must be familiar with in order to contribute.
You want to reduce the barriers to contribution to your feature by allowing it to be developed without requiring a Firefox build environment.
You want to reduce the barriers to contribution to your feature by having the core development of it occur in an environment and workflow that are most productive for you and your team.
You want to improve the maintainability of your code by restricting the breadth of the code to single directory instead of the entire Firefox codebase.

You can also read the Jetpack Feature principles, which talk about some of the reasons for building features as add-ons.

Invalid reasons to ship a feature as a bundled add-on:

If you want to move faster than the Firefox release cycle, bundling as an add-on is not the solution for you. The minimum time for a feature to ship in the Firefox stable release is 12 weeks. If that is too long for you, then your add-on is probably not ready for production, and is still in active development or an experimental phase. Your feature best belongs in an add-on that is *not* shipped with Firefox.

Is your feature self-contained enough to be developed as a standalone body of code? If you find yourself fighting battles to get access to internals that are not well-exposed, then perhaps the feature should be built into Firefox instead.

Does your feature have any binary code? The cost of binary code in add-ons is high in several ways. TODO: Enumerate those ways here.

Code that ships with Firefox, whether in an add-on or not, is required to not regress any of the suites of performance or unit tests. It's highly recommended that you rent a project branch for a period of time before attempting to land your project on mozilla-central, in order to have those unit and performance tests regularly run against your code.

Code that ships with Firefox, whether in an add-on or not, is required to have automated tests that ensure it's quality and reduce the possibility of regression.

Create a directory for your add-on in /browser/app/profile/extensions. Name this directory after the id of your add-on. This is the root directory for your add-on. The raw source files of your add-on should be put in there. Do not pre-package your add-on.
Add that directory to the DIRS section in /browser/app/profile/extensions/Makefile.in. The build system will package your add-on as part of the build process.
In your add-on source directory, create a Makefile.in file based on this example for PDF.js.
In your add-on source directory, rename your install.rdf file to install.rdf.in and add a replaceable marker for the Firefox minVersion and maxVersion tags, as done in this example for PDF.js.
Include the packaged add-on in Firefox by listing the file in /browser/installer/package-manifest.in.

Example: PDF.js add-on

Optional: If you want a build-time flag to control whether the add-on is bundled or not, look at how the Feedback add-on has done it: http://mxr.mozilla.org/mozilla-central/search?string=SHIP_FEEDBACK.

Document how to include tests.
Document how to include localized strings.
Document how toggle whether the add-on is enabled or disabled by default. (Needed?)
Add a note about add-on blocking, currently being tracked in bug 738674.
Some questions that need answers here: "If I have add-on sync enabled will that then propogate across browsers even if I have preferences sync disabled? Will about:support list the extension? Crash reports? Will the compatibility check on upgrade check for updates to pdf.js?"