Revision as of 00:58, 15 November 2014

Guiding Principles

Mozilla aims to advance the state of the open Web with new APIs. In the last few years, Mozilla has shipped experimental APIs with a "moz" prefix to indicate their lack of standardization (e.g., mozRequestAnimationFrame()). Unfortunately, this approach turned out to be harmful to the Web as experimental APIs ended up being used in some websites before the APIs were ready. In many cases, this meant that we were unable to innovate on certain APIs because to change them would break content on the Web. Therefore, to allow us to continue innovating without negatively affecting content on the Web, Mozilla will no longer ship new "moz"-prefixed APIs (see Henri Sivonen's proposal).

We will instead make experimental APIs available behind preferences which can be toggled through about:config. Once we feel there is an acceptable level of consensus in the Web community about the stability of an API and we feel it is ready, we will make it generally available to the platform (more details below on this process). We feel this strikes the right balance between allowing developers to experiment with new APIs, while at the same time protecting the Web from being exposed to new functionality prematurely.

Special Cases

There may be special cases where we deviate from this goal. New user-facing products like Firefox OS may need to ship APIs that have not yet been embraced by other browser engines or thoroughly discussed by standards bodies. This allows Mozilla to provide functionality that other browser engines aren't working on or the majority of the Web community isn't interested in at that time. Examples of such functionality include telephony and Bluetooth. This functionality is most often only exposed to Firefox OS applications of elevated privileges and not via the Firefox OS browser application. We will avoid exposing such functionality to the web at large. Developing these features without much involvement from the Web community comes with the price of temporary proprietary APIs. Products such as Firefox OS ship these APIs as a part of their product but not to the broader web when they are not ready for such exposure. This clearly indicates their lack of standardization at that time and limits the number of developers relying upon them. Mozilla will learn from efforts such as Firefox OS and use this knowledge to inform various standardization efforts. Our aim is to standardize our proprietary APIs as soon as possible so they become available on a royalty-free basis for the benefit of the Web community at large.

Guidelines for Mozillians developing new APIs

The following is put forward as a set of guidelines for Mozillians -- especially module owners and peers -- to refer to while developing new APIs for the Web. The primary question that must be asked is:

Is this good for the Web?

If the answer to that question is yes, look below for some guidance on how you should proceed with shipping your new feature. Note that trivial changes need not worry about these suggested guidelines.

When is an API ready to be shipped by Gecko?

APIs which Mozilla makes available by default to the Web on the release channel should be "ready". This can mean that they are de jure standards (ex. W3C recommendations) or de facto standards. Indications that an API is ready for shipping to the Web include:

1. other browser engines ship compatible implementations in their releases or behind a preference with clear signals it will graduate to being on by default
2. other browser engines state their intention to ship a compatible implementation
3. a large number of web developers indicate their satisfaction with the API design
4. there exists a specification that is no longer at risk of significant changes, is on track to become a standard with a relevant standards body, and is acceptable to a number of applicable parties and other browser engines

How do we know what other browser engines think?

• some of them participate in dev-platform discussions
• watch for positive signals on W3C mailing lists such as public-script-coord, etc.
• watch for "intent to implement" emails on mailing lists such as blink-dev
• lack of feedback will not delay our implementation as it may simply indicate lack of interest at that time from another browser engine

How do we know what web developers want?

• Mozilla's Developer Engagement coordinates a Open Web Apps UserVoice forum
• chromestatus.com has a column for new features entitled "Documented or perceived web developer views"

How do we let other browser engines know what we think?

• participate in public discussions of proposed features
• blog and/or tweet about proposed features
• comment on "intent to implement" threads on blink-dev

Suggested implementation process

If your work is going to expose a new web API to the web or non-trivially change an existing API, it is requested that you follow these steps:

1. Email dev-platform declaring your intent to implement this API. If you are implementing an API that is working its way through a standards body process such as the W3C's, it's best to email as soon as possible (ie. before W3C CR status if possible).
2. Implement as normal. Code review rounds will take place, etc. Module owners or their designated peers will provide a super-review for all interface changes.
3. Land potentially disruptive APIs behind a preference which is off by default

Turning a preference on by default

When you are satisfied that your new API is stable enough for exposure to the Web at large (see above), it is requested that implementors send another email to dev-platform declaring their intent to ship. Among other things, this email serves to inform those that are interested in the new API but have not been closely following the implementation bug(s).

Email templates

Intent to Implement

To: dev-platform@lists.mozilla.org
Subject: Intent to implement: <your feature goes here>

Summary: elevator pitch for the new functionality including benefits to web developers
Bug: link to main implementation tracking bug
Link to standard: if no formal specification exists yet, link to public discussions with other browser vendors
Platform coverage: where will this be available? Android, Desktop, Firefox OS, only exposed to privileged apps (certified app-only functionality does not require an email), etc.
Estimated or target release: in which version do you want to/plan to release this?
Preference behind which this will be implemented: if applicable, how can interested parties test this before it ships pref'd on by default?

Intent to Ship

To: dev-platform@lists.mozilla.org
Subject: Intent to ship: <your feature goes here>

As of <target date> I intend to turn <feature> on by default [<on these platforms>]. It has been developed behind the <pref> preference. Other UAs shipping this or intending to ship it are <details>.

This feature was previously discussed in this "intent to implement" thread: <https://groups.google.com/forum/#!forum/mozilla.dev.platform>.

Bug to turn on by default: link to main relevant bug (https://bugzilla.mozilla.org/show_bug.cgi?id=)
Link to standard: note here what has transpired with the specification since your original intent to implement email was sent