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.

Guidelines

Mozilla aims to advance the state of the open web with new APIs. Toward this end,

Mozilla will not hurt the web by exposing a new web 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 no longer do this. See Henri Sivonen's proposal.

Mozilla will not ship moz-prefixed web APIs

Scope

At this time, we are specifically focusing on new web APIs and non-trivial changes to existing APIs. We are explicitly not focusing on CSS, WebGL, WebRTC, network protocols, or other existing features/properties. In the future, pending module owner agreement, we may extend this policy beyond web APIs to other web-exposed features.

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 standardized. This can mean that they are de jure standards (ex. W3C recommendations) or de facto standards. Indications that an API is standardized enough for shipping to the open web include:

1. other browser engines ship compatible implementations, either in their release or in other channels with clear signals it will graduate to a release
2. other browser engines state their intention to ship a compatible implementation
3. 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

Mozilla seeks feedback from other browser engines during development and implementation of web APIs. Lack of feedback will not stop our efforts as it may simply indicate lack of interest at that time from another browser engine. We will attempt to reciprocate this feedback to other browser engines when they are developing a feature or API that we believe to/will be relevant, even if we won't implement it ourselves in the short term.

Exceptions

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. Products such as Firefox OS would ship these APIs as a part of their product but not to the broader web, thus clearly indicating their lack of standardization and limiting the number of web developers relying upon them. When rare situations such as this arise, API standardization must begin within one year of shipping the initial version of such products.

Since APIs will very likely change as they are standardized and some developers will build things on top of non-standardized versions of these APIs, we will try to reasonably assist affected developers where possible. Should an API's standardization process fail, it is unclear what will be done with the non-standard API that has been shipped since some people will surely be relying upon it, even if it is only a part of one product and not available to the web at large. FIXME should we ship these APIs prefixed or under a window.mozilla namespace or just with their "normal" name?

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 (FIXME CC joint list with Blink) (FIXME create email template (Blink's template)). 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. We are working on a Mozilla API review team which will be Mozillians who have experience designing JS APIs and will have at least one representative from the JS team at all times. This team will monitor dev-platform for intent to implement emails and can assist with ensuring APIs are "webby" and friendly to JS developers.
3. When new APIs are being implemented, a super-review from a member of the API review team is requested. Module owners can choose to waive this request if they feel it is not necessary.

Shipping Process

Once the above process for implementation has concluded, it is requested that implementors must send another email to dev-platform declaring their intent to ship (FIXME: create email template (Blink's template)). 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.

Retroactive applicability

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. FIXMEs above
2. set up a joint mailing list with Blink for intent to implement/ship
3. keep track of progress towards standardization for in-development APIs
4. explicitly call out that API exposure for Firefox OS apps (ie. certified, packaged) doesn't fit into this policy?
5. evaluate effectiveness of guidelines, possibly considering a mechanism to limit exposure (ex. commit hook for all new WebIDL files)