Interface Compatibility

The Mozilla platform is constantly evolving. As we add new features to the web and to our applications, programming interfaces change. The rules which govern interface changes are different depending on the consumers and the languages involved.

Web Content

APIs which are visible to web content are not modified, except as a last resort when inherent security vulnerabilities or incompatibility with other browsers make it the only option. Any changes, including new features, must have super-review.

One exception to this rule is APIs which are explicitly shipped with Mozilla prefixes as a technology preview. This includes CSS properties that begin with the -moz- prefix (e.g. -moz-box-shadow), or JavaScript APIs that begin with the moz prefix (e.g. canvasrenderingcontext.mozDrawText). These APIs may be removed or replaced with standard interfaces in future releases of Mozilla.

Jetpack

Documented APIs which are shipped as part of the Jetpack SDK are designed to work in future versions of Firefox. Achieving this compatibility may require rebuilding the extension with a new version of the Jetpack SDK.

JavaScript/XUL Interfaces

Traditional extensions written using XUL overlays and XPCOM have access to the full power of the Mozilla platform. With the power, however, comes the understanding that the Mozilla platform is constantly changing and many APIs may change in future versions of Firefox.

• In micro/maintenance releases, there should be no incompatible changes to interfaces, except as a last resort when a security fix leaves no other option. This includes not only XPCOM interfaces, but JavaScript functions, XBL bindings, and any other visible behavior.
• Between major releases, there is no guarantee of interface stability. Changes should not be taken lightly, however: especially if a change is likely to affect many extensions, the change should try to maintain backwards compatibility by using optional/default parameters or other JavaScript techniques.
• Where appropriate, new APIs should be designed so that they are compatible with future plans, and clients do not need XPCOM boilerplate. This may involve using JavaScript modules, passing named parameters using objects, or other similar techniques.

Binary Interfaces

Traditionally, Mozilla has maintained a set of XPCOM interfaces and functions with the @status FROZEN marking. Using these interfaces, and using dynamic calls to QueryInterface, it has been possible to write binary XPCOM components which were compatible with multiple versions of Firefox. Beginning with Mozilla 2 (Firefox 4), this will no longer be supported: all @status markings have been removed, and extensions that use binary components will need to recompile for each major version they wish to support.

• JS-ctypes is the recommended way for extensions to call into OS or third-party native code. You should strongly consider migrating existing code to use js-ctypes instead of binary components.
• If necessary, it is possible for an extension to support multiple versions by shipping multiple shared libraries (DLLs) in the same extension package, and selecting the correct version using versioning flags in its chrome.manifest file.
• JSAPI, NSPR, NSS, and other libraries which are currently shipped as separate shared libraries may be integrated into libxul, and extension authors should avoid linking against them.