ExposureGuidelines

Goal

Mozilla aims to advance the state of the open web with new features, enhanced security, and the removal of unnecessary cruft. We will not hurt the web by exposing an API in such a way that a web developer can detect it (1) before it's ready. In the past we have shipped APIs with "moz" prefixes to indicate their lack of standardization but we will no longer do this (see Henri Sivonen's proposal). Note that at this time, we are specifically focusing on JS APIs and not on other web-facing properties (ex. CSS).

Process Overview

1. Is the API "ready"?
2. Is the API standardized or on its way to being so?
3. Declaration of intent
4. API review
5. Implementation
6. Shipping
7. Policy enforcement

Declaring Intent

Developers of new APIs intended to be exposed to the web at large via Mozilla products must send an email to dev-platform and dev-webapi declaring their intent to implement this API. This email must have a subject line that begins with "Intent to implement:" and whose body describes the feature and links to relevant documentation. It must also demonstrate that an API is standardized as defined below. Implementors must also use this email to request API review from the Mozilla API review team. These emails must be sent early on in the process of any new API's development, especially if this work is being done as part of a standards body. This will expose the API to a larger audience which can help improve its quality and avoid APIs which are designed by domain experts but aren't "webby" or friendly to JS developers. The API review team can help with the latter concern.

API review

The Mozilla API review team will consist of Mozillians who have experience designing JS APIs and will have at least one representative from the JS team at all times. This team will respond to review requests for all proposed APIs. Disputes between the API review team and the API developers will be decided by the module owner for the API's area.

Standardization

APIs for the open web must be standardized which can mean that they are de jure standards (ex. W3C recommendations) or de facto standards. For the purposes of this policy, an API is considered to be standardized if any of the following apply:

1. the relevant standards body declares it ready for implementation
2. at least two other browser vendors ship a compatible implementation of this API
3. at least one other browser vendor ships -- or publicly states their intention to ship -- a compatible implementation of this API and there is a specification that is no longer at risk of significant changes, on track to become a standard with an relevant standards body, and acceptable to a number of applicable parties

Exceptions

Exceptions to the standardization rules above include:

1. during the first 12 months of development of new user-facing products, APIs that have not yet been embraced by other vendors or thoroughly discussed by standards bodies may be shipped [with a Mozilla vendor prefix? (thus clearly indicating their lack of standardization and limiting any market share they may attain)]
2. ecosystem- and hardware-specific APIs that are not standard or of interest to the broader web at that time (or ever) may be shipped in a way to limit their harm of the broader web (ex. only on a device or only in specific builds with clear disclaimers about applicability of exposed APIs). An example of this is the FM Radio API for Firefox OS.
3. APIs which only Mozilla is interested in at that time. In cases such as this (which will likely be rare), Mozilla will solicit feedback from as many relevant parties as possible, begin the standardization process with a relevant standards body, and create a test suite as part of the standards process. An example of this is the Push Notifications API.
4. APIs which will be hidden behind preferences. APIs like this can also skip the required API review (see below).

Implementation

Once there has been a public declaration of intent to implement and the API has been approved by the API review team, implementation should proceed as with any new Mozilla project. Code review rounds will take place, etc. When new APIs are being implemented [or non-trivial changes are being made to APIs that are already shipping in a release -- add in later], a super-review is required from a member of the API review team. As with code reviews, disputes will be resolved by the applicable module owner.

Shipping

Once code has been reviewed and an sr+ from a member of the API review team has been granted, implementors must send another email to dev-platform. The subject of this email must begin with the "Intent to ship:" and the body must reference relevant documentation and the bug where the code has been implemented. Once one week has passed [is the time period necessary?], if there have been no dissenting voices and all of the above steps have been followed, the code may be checked in to mozilla-central.

Branches

We sometimes only ship experimental software on Nightly and/or Aurora. While this greatly limits the exposure of unproven APIs to the Firefox userbase and the broader web, it can have unintended consequences such as developers and users having different features available in their browsers. We are still deciding what to do here.

Policy enforcement

We are considering implementing a commit hook ensuring all new WebIDL files [and changes to existing ones -- add in later] have the required sr+. No decision has been made at this time.

Cleanup

This policy is new and we have work to do to clean up previous divergences from it. One example is window.navigator. We are committed to making the necessary changes to align Mozilla's codebases with this policy.

TODO for this policy

1. should we have a joint mailing list with Blink for intent to implement/ship?
2. how do we keep track of progress towards standardization for in-development APIs?
3. how do levels of API exposure for Firefox OS apps (certified, packaged, etc.) fit into this policy?
4. should we enforce this by putting all WebIDL files into a new module?