ExposureGuidelines

	THIS PAGE IS A WORKING DRAFT
	The page may be difficult to navigate, and some information on its subject might be incomplete and/or evolving rapidly. If you have any questions or ideas, please add them as a new topic on the discussion page.

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 a new 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 new JS APIs and not on CSS, WebGL, WebRTC, or other existing features/properties.

Process Overview

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

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 engines ship (regardless if it's behind a flag or not in their equivalent of beta or release) -- a compatible implementation of this API
3. at least one other browser engines ships (regardless if it's behind a flag or not in their equivalent of beta or release) -- 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 browser engines or thoroughly discussed by standards bodies may be shipped only as a part of this product, 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 solving use cases which no browser engine other than Gecko is interested in at that time. In cases such as this, 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).

Declaring Intent to Implement

Developers of new APIs intended to be exposed to the web at large via Mozilla products must send an email to dev-platform 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 (ie. before W3C CR status). This will expose the API to a(n even) 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.

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, 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.

Intent to Ship and 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. This email is mostly a courtesy to those that are interested in the new API but have not been closely following the implementation bug(s).

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 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?