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.

Mozilla aims to advance the state of the open web with new features. 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.

See below for guidelines around knowing when something is ready to be shipped.

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 not on CSS, WebGL, WebRTC, network protocols, or other existing features/properties. In the future, we may extend the policy below beyond web APIs to other web-exposed features, pending module owner agreement.

When is an API is ready to be shipped?

APIs which Mozilla makes available to the open web (not those behind a flag) in a release 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
2. the relevant standards body declares it ready for implementation
3. other browser communities state their intention to ship a compatible implementation
4. there exists 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

Suggestions for Module Owners Evaluating API "Readiness"

It is difficult to define "do the right thing" and it is also difficult to codify a set of exceptions to the guiding principles. Some guidance around exceptions to Mozilla's attempt to ship only standardized web APIs follows.

• new user-facing products like Firefox OS can ship APIs that have not yet been embraced by other browser engines or thoroughly discussed by standards bodies 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
  • API standardization must begin within one year of shipping the initial version of such products
  • 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 assist affected developers to an appropriate extent, with the extent of our efforts made on a case-by-case basis.
  • 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
  • FIXME: should we ship these APIs prefixed or under a window.mozilla namespace or just their "normal" name?
• Mozilla will seek 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. Mozilla will attempt to provide feedback to other browser engines when they are developing a feature or API that we will believe to be relevant, even if we won't implement it ourselves in the short term.

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. This will act as a public service announcement and allow all interested parties to comment on technical or related issues. The email must also demonstrate that an API is standardized as defined below. A third use of this email will be 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).

FIXME Add something here about dissenting voices and waiting x days for them to respond or allow shipping to go ahead.

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?