ExposureGuidelines

Adding features

One way Mozilla aims to advance the state of the web platform is with new features. Always ask: Is this good for the web?

If you aim to expose a new feature to the web or change an existing feature, please follow these steps:

1. Email dev-platform declaring your intent to prototype. (It is okay to skip this step for small changes.)
   1. If you are implementing a feature that is working its way through a standards body process such as the W3C's, it's best to email as soon as possible (i.e., 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.
   1. Restrict the feature to secure contexts.
   2. Ensure the feature has web-platform-tests coverage.
   3. Land potentially disruptive features behind a preference which is off by default.
3. Email dev-platform declaring your intent to ship on Firefox Release.
4. If there's no negative feedback, ship.

Intent to prototype

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

Summary: elevator pitch for the new functionality including benefits to users and web developers.
Bug: link to Bugzilla (tracking) bug.
Standard: link to standard or link to public discussions with other browser vendors.
Platform coverage: where will this be available? Android, Desktop, only exposed to privileged apps (certified app-only functionality does not require an email), etc.
Preference: if applicable, how can interested parties test this before it ships pref'd on by default?
DevTools bug: link to a Developer Tools bug coordinating work with the DevTools team to build tools for this feature.
Other browsers: address with "shipped" (since version X, behind what flags if any), "intent emailed" (mailing list URL), or "considering" (citation).
web-platform-tests: Please link to the test suite. If any part of the feature is not tested by web-platform-tests, or if you had to write gecko-only tests for parts of the feature, please include links to one or more of:

• A web-platform-tests issue explaining why a certain thing cannot be tested (example).
• A spec issue for some change that would make it possible to test (example).
• A Bugzilla bug for the creating web-platform-tests.

Suggested additions

The above is the minimum required that should be in an "Intent to prototype" email. If you've covered those, you're good, and brevity is a virtue.

If you're looking for extra credit, or to preempt common questions, consider adding any or all of the following (all based on existing dev-platform examples, and questions asked on dev-platform in response to intent to ship emails).

• Link to standards-positions discussion: Link to a discussion in mozilla/standards-positions about what we think about the specification.
• How stable is the spec: Note that even if it's unstable that shouldn't stop us implementing; that mostly affects shipping. So as long as we're pretty sure that the basic set of functionality is stable, even if the actual names of the values are not, implementing makes sense.
• Security & Privacy Concerns: consider providing a link to answers in this security/privacy questionnaire for a spec feature, if the spec doesn't already answer it. In particular, consider if the spec exposes new information about a user's computer or behavior that can contribute to fingerprinting.
• Web designer / developer use-cases AKA Why a developer would use Feature X?: Provide a URL to at least briefly documented use-cases for web designers and developers that illustrate why and when they would use this feature.
• Example: Provide a brief code sample on how to use the API. Even with a formal specification, not everyone will know about the feature just from the name of the spec. An example will make it easier to understand how this feature can be used. This can either be an inline code sample, or a direct link to an example on the web.

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. Status in other browsers is <details>.

Bug to turn on by default: link to main relevant bug (https://bugzilla.mozilla.org/show_bug.cgi?id=) Please set the dev-doc-needed keyword.

This feature was previously discussed in this "Intent to prototype" thread: <https://groups.google.com/forum/#!forum/mozilla.dev.platform>. If anything changed since that thread please include that information in this email.

It's acceptable to merge the "intent to prototype" into the "intent to ship" email as long as all the relevant requirements are met.

Removing features

Occasionally there is a need to remove features. These could be features that are proprietary to Mozilla, were standardized but never got adopted by all browsers, or features that are so bad that all browsers want to get rid of them together.

In order to make this possible while impacting users as little as possible the following steps are to be taken:

• Gather telemetry on the feature.
• Consult dev-platform with an intent to unship that includes the telemetry data.
• Indicate in the developer console whenever the feature is used that it's deprecated and might be removed. It's best to avoid doing this until there's agreement that the feature can be removed (which requires telemetry) as otherwise developers are needlessly spammed in the console.
• Remove the feature when the telemetry data and dev-platform agreement indicate it can be.

Intent to unship

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

As of <target date> I intend to remove <feature> [<on these platforms>]. Status in other browsers is <details>.

Bug to remove: link to main relevant bug (https://bugzilla.mozilla.org/show_bug.cgi?id=) Please set the dev-doc-needed keyword.

<Include rationale, telemetry analysis, links to related discussions if any, and developer console suggestions.>

See Also

• WebAPI/DesignGuidelines
• WebAPI/WebIDL_Review_Checklist
• Chrome/Blink change process
  • Chrome/Blink process for Launching Features in particular

FAQ

When is a feature ready to ship?

Features 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 (e.g., a W3C Recommendation) or de facto standards. Indications that a feature 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 feature 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 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 know what other browser engines think?

• Some of them participate in dev-platform discussions
• Watch for positive signals on the specification's discussion forum (likely a GitHub repository)
• Watch for "intent to *" emails on mailing lists such as blink-dev

Note: 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 let other browser engines know what we think?

• By documenting our position on [standards-positions https://github.com/mozilla/standards-positions].
• Participating in public discussions of new features.
• Comment on "intent to *" threads on blink-dev.

What about prefixes?

In the past, Mozilla has shipped experimental features 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 features ended up being used in some websites before they were ready. In many cases, this meant that we were unable to innovate on certain features because to change them would break content on the web. Browsers have in some cases also been forced to implement each other's prefixed features. Therefore, to allow us to continue innovating without negatively affecting content on the web, Mozilla will no longer ship new "moz"-prefixed features (see Henri Sivonen's proposal).

We will instead prototype features 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 feature and we feel it is ready, we will make it generally available to the web platform (more details below on this process). We feel this strikes the right balance between allowing developers to experiment with new features, while at the same time protecting the web from being exposed to new functionality prematurely.

Who decides?

If the dev-platform thread results in a conflict, the respective module owner is responsible for resolving that conflict and making a decision on how to proceed.