Add-ons using the techniques described in this document are considered a legacy technology in Firefox. Don't use these techniques to develop new add-ons. Use WebExtensions instead. If you maintain an add-on which uses the techniques described here, consider migrating it to use WebExtensions.
From Firefox 53 onwards, no new legacy add-ons will be accepted on addons.mozilla.org (AMO).
From Firefox 57 onwards, WebExtensions will be the only supported extension type, and Firefox will not load other types.
Even before Firefox 57, changes coming up in the Firefox platform will break many legacy extensions. These changes include multiprocess Firefox (e10s), sandboxing, and multiple content processes. Legacy extensions that are affected by these changes should migrate to WebExtensions if they can. See the "Compatibility Milestones" document for more.
A wiki page containing resources, migration paths, office hours, and more, is available to help developers transition to the new technologies.
Developers using the SDK's APIs need to know how far they can trust that a given API will not change in future releases. At the same time, developers maintaining and extending the SDK's APIs need to be able to introduce new APIs that aren't yet fully proven, and to retire old APIs when they're no longer optimal or supported by the underlying platform.
The API lifecycle aims to balance these competing demands. It has two main components:
- a stability index that defines how stable each module is
- a deprecation process that defines when and how stable SDK APIs can be changed or removed from future versions of the SDK while giving developers enough time to update their code.
Stability Index
The stability index is adopted from node.js. The SDK uses only four of the six values defined by node.js:
| Experimental | The module is not yet stabilized. You can try it out and provide feedback, but we may change or remove it in future versions without having to pass through a formal deprecation process. |
| Unstable | The API is in the process of settling, but has not yet had sufficient real-world testing to be considered stable. Backwards-compatibility will be maintained if reasonable. If we do have to make backwards-incompatible changes, we will not guarantee the module will go through the formal deprecation process. |
| Stable | The module is a fully-supported part of the SDK. We will avoid breaking backwards compatibility unless absolutely necessary. If we do have to make backwards-incompatible changes, we will go through the formal deprecation process. |
| Deprecated | We plan to change this module, and backwards compatibility should not be expected. Don’t start using it, and plan to migrate away from this module to its replacement. |
The stability index for each module is written into that module’s metadata structure, and is displayed at the top of each module's documentation page.
Deprecation Process
Deprecation
In the chosen release, the SDK team will communicate the module's deprecation:
- update the module's stability index to be "deprecated"
- include a deprecation notice in the release notes, the Add-ons blog, and the Jetpack Google group. The deprecation notice should point developers at a migration guide.
Migration
The deprecation period defaults to 18 weeks (that is, three releases) although in some cases, generally those out of our control, it might be shorter than this.
During this time, the module will be in the deprecated state. The SDK team will track usage of deprecated modules on addons.mozilla.org and support developers migrating their code. The SDK will continue to provide warnings:
- API documentation will inform users that the module is deprecated.
- Attempts to use a deprecated module at runtime will log an error to the error console.
- The AMO validator will throw errors when deprecated modules are used, and these add-ons will therefore fail AMO review.
All warnings should include links to further information about what to use instead of the deprecated module and when the module will be completely removed.
Removal
The target removal date is 18 weeks after deprecation. In preparation for this date the SDK team will decide whether to go ahead with removal: this will depend on how many developers have successfully migrated from the deprecated module, and on how urgently the module needs to be removed.
If it's OK to remove the module, it will be removed. The SDK team will remove the corresponding documentation, and communicate the removal in the usual ways: the release notes, the Add-ons blog, and the Jetpack Google group.
If it's not OK to remove it, the team will continue to support migration and aim to remove the module in the next release.