A lifecycle for the Add-on SDK’s APIs

Until now we’ve not had a very well-defined lifecycle for APIs in the Add-on SDK. We’ve said, broadly, that APIs in the addon-kit package are “supported”, meaning we won’t change them “unless absolutely necessary”, while APIs in the lower-level api-utils package are “not fully stabilized”, meaning that we expect to make incompatible changes to them.

There are some exceptions to this broad rule: some newer modules in addon-kit, like simple-prefs, have been marked as “experimental”, and we’ve deprecated a few APIs in addon-kit, such as the global postMessage() and on() functions in content scripts. More recently we’ve landed a lot of changes to the SDK’s internals, and as a result several modules in api-utils are effectively obsolete and should no longer be used.

Without a process for promoting modules from “experimental” to “supported”, for deprecating APIs, or for removing deprecated APIs, things tend to stagnate:

new modules stay “experimental” for longer than they should, meaning developers can’t rely on them not to change unexpectedly

deprecated APIs hang around indefinitely, increasing the support burden and making the SDK more confusing to use

When the Jetpack team met up a few weeks ago one of the things we talked about was a process for defining and communicating the stability of our APIs, and for deprecating and eventually removing obsolete APIs.

The lifecycle we’ve drafted has two main components:

a “stability index”, that defines how stable each module is

a deprecation process that is intended to enable the SDK to remove or change APIs when necessary, while giving developers enough time to update their code.

Stability Index

The stability index is adopted from node.js. Each module is assigned one of six values:

Experimental: this means that 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.

Stable: this means that 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.

What’s Next?

This process is itself still in the “experimental” state! If you have any feedback about how we can make it better, we’d love to hear from you in comments to this post or via any of the usual channels:

3 responses

one serious issue is the existing documentation for old versions of the SDK. this happened to me several times, after searching for some module (probably via google) i end up on a page documenting an old version, but didn’t notice..

i think that old docs should be clearly labeled as outdated the minute the new SDK version is officially released, and each page should have a direct link to the newest version of the docs..