ExposureGuidelines: Difference between revisions

From MozillaWiki
Jump to navigation Jump to search
(Add links for intenttoship bot)
 
(111 intermediate revisions by 24 users not shown)
Line 1: Line 1:
{{Draft}}
<span style="float:right">__TOC__</span>
'''Always ask: ''Is this good for the web?'''''


=Introduction and goals=
=Adding or changing features=
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 ([https://groups.google.com/a/chromium.org/d/msg/chromium-dev/HN2e4sGbVus/OIEWgN1yi04J 1]) before it's ready.''
This process applies to all code contributions to Firefox that introduce, modify, or remove features that change how the web platform operates.


See below for guidelines around knowing when something is ready to be shipped.
If you aim to expose a new feature to the web or change an existing feature, please follow these steps:


In the past we have shipped APIs with "moz" prefixes to indicate their lack of standardization but we no longer do this.
# [[#New features|Evaluate the new feature]] or [[#Changing or evolving features|change to an existing features]].
See [https://groups.google.com/forum/#!topic/mozilla.dev.platform/34JfwyEh5e4 Henri Sivonen's proposal].
# Email [https://groups.google.com/a/mozilla.org/g/dev-platform dev-platform] declaring your [[#Intent to prototype|intent to prototype]]. (It is okay to skip this step for small changes*.)
# Implement as normal. Code review rounds will take place, [https://github.com/w3c/web-platform-tests web-platform-tests] will be written, etc.
# Email [https://groups.google.com/a/mozilla.org/g/dev-platform dev-platform] declaring your [[#Intent to ship|intent to ship]] on [[Release_Management/Release_Process|Firefox Release]].
# If there's no negative feedback, ship it!


::''Mozilla will not ship moz-prefixed web APIs''
<nowiki>*</nowiki>If you’re not sure, it’s unlikely to be a small change.


Note that 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.
=New features=


=When is an API is ready to be shipped?=
There’s a lot of nuance that goes into adding a feature to the web. Mozilla sets a high bar for any changes we make to the web.
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:


# other browser engines ship compatible implementations
Making new features available requires some care and consideration.
# the relevant standards body declares it ready for implementation
# other browser communities state their intention to ship a compatible implementation
# 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"=
==Establish that the feature is important==
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
We have finite resources and we want to ensure that we develop features that are important.  Reasons might include:
** API standardization must begin '''within one year of shipping''' the initial version of such products
* It’s of strategic importance to Mozilla.
** 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.
* It contributes to [https://www.mozilla.org/en-US/about/manifesto/ Mozilla’s mission].
** 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
* This will make us the second/third browser to ship this, enabling more web developers to use it. That is, this helps with web compatibility and moves the web forward by having another independent implementation.
** 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=
==Ensure that the feature is standardized==
Developers of new APIs intended to be exposed to the web at large via Mozilla products must send an email to [https://lists.mozilla.org/listinfo/dev-platform 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 [[#Standardization|defined below]].  A third use of this email will be to request API review from the Mozilla [[Special:MyPage/APIExposurePolicy#API_review|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 [http://www.w3.org/2005/10/Process-20051014/tr#q74 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=
Mozilla is committed to standardization as the basis for evolving the Web.  We want to ensure that features are good for our users and have broad support from other browsers, web developers, and the broader community. The [[standards]] process is how we ensure that features meet these expectations.
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=
Our goal is that all new web-facing features are based on a specification that is the product of a recognized standards body.
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=
===Standardization requirements for prototypes===
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.
If a specification for a feature is not the product of a standards body, your intent to prototype needs to identify what steps have been taken to ensure that it will be.  You should identify which standards body you believe should take the work on.  Include a link to a record from that standards body that tracks the feature becoming an official product.


==Branches==
What you minimally need to show might differ according to the processes of the standards body:
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==
* '''W3C''' - an issue raised on a working group charter (not a community group)
We are considering implementing a commit hook ensuring all new WebIDL files have the required sr+.  No decision has been made at this time.
* '''WHATWG''' - an issue raised on the appropriate standard(s)
* '''IETF''' - an explicit request for adoption by a working group
* '''TC39''' - a link to a proposal at stage 1 or higher
* For other bodies, a request for consideration according to the procedures of the body


=Cleanup=
Being able to prototype new features allows us to learn about them, but experimentation serves to inform our choices in standards bodies.  Features that have not been discussed within the processes of a standards body will require extra scrutiny to ensure that it is safe to prototype.  This applies especially to W3C work that is not the product of a working group or community group; the same applies to individual submissions to the IETF.
This policy is new and we have work to do to clean up previous divergences from it.  One example is [https://developer.mozilla.org/en-US/docs/Web/API/window.navigator window.navigator].  We are committed to making the necessary changes to align Mozilla's codebases with this policy.


=TODO for this policy=
===Standardization requirements for shipping features===
# should we have a joint mailing list with Blink for intent to implement/ship?
 
# how do we keep track of progress towards standardization for in-development APIs?
An intent to ship must include an update on the standardization status of the feature.  We expect that shipping features will be further advanced in the standards process when they ship.
# how do levels of API exposure for Firefox OS apps (certified, packaged, etc.) fit into this policy?
 
# should we enforce this by putting all WebIDL files into a new module?
Your intent to ship should include information that shows not only that the standards body has adopted the work, but also that there is consensus that the feature is ready to be shipped.  What evidence is necessary will vary, but generally this will be:
 
* '''W3C''' - the specification is at the Candidate Recommendation [https://www.w3.org/2021/Process-20211102/#maturity-levels maturity level] or more advanced; shipping from a Working Draft or a less advanced specification requires evidence of agreement within the working group that shipping is acceptable
* '''WHATWG''' - the changes have been merged into a standard; an open pull request requires additional evidence of agreement among implementers that shipping is acceptable
* '''IETF''' - a working group draft that has been passed to the IESG for publication by the working group; a draft working group in an earlier state should show evidence that shipping is acceptable to the working group
* '''TC39''' - the proposal is at stage 3 or higher
* The product of other bodies will be assessed individually
 
In all of these cases, try to show that there are no significant unresolved issues with a specification and that there are no objections to shipping it. Simply showing that there is support for a feature is less useful.
 
Shipping features that don’t meet these requirements is still possible, including features that don't show broad agreement that shipping is acceptable.  If your feature needs an exception to this rule, please reach out to [[Modules/Firefox_Technical_Leadership|Firefox Technical Leadership]]. Any intent regarding a non-standard feature might need to include additional safeguards such as experimentation and data collection plans, risk assessments, and rollback strategies.
 
==Ensure that Mozilla has a position on the feature==
 
[https://github.com/mozilla/standards-positions standards-positions] is where Mozilla formalizes positions on new features.  Open an issue there if one does not already exist.
 
=Changing or evolving features=
 
When making changes to existing features or even removing existing features many of the considerations stated for [[#New features|evaluating new features]] apply, but one thing that is quite different is that telemetry might be important here as in general Mozilla is pretty averse to shipping breaking changes. Coordination with the relevant standard and other browsers is usually the way to go.
 
 
=Email templates for new or changed features=
 
When announcing your intent to prototype or ship a feature, using these templates ensures that you don’t miss anything critical.
 
==Intent to prototype==
 
<blockquote>
'''To''': <tt>dev-platform@mozilla.org</tt><br>
'''Subject''': Intent to prototype: <your feature goes here>
 
''Summary'': [https://en.wikipedia.org/wiki/Elevator_pitch elevator pitch] for the new functionality including benefits to users and web developers.<br>
''Bug'': link to Bugzilla (tracking) bug.<br />
''Specification'': link to the specification (see [[#Standardization requirements for prototypes|details above]])<br />
''Standards Body'': identify the standards body responsible for standardizing this feature if that is not obvious from the specification; if the specification is not already adopted by a standards body, link to the issue or a discussion about adoption of the work (if no discussion exists, please start that process before filing this intent)<br />
''Platform coverage'': where will this be available? Android, Desktop, only exposed to privileged apps (certified app-only functionality does not require an email), etc.<br />
''Preference'': if applicable, how can interested parties test this before it ships pref'd on by default?<br />
''DevTools bug'': link to a [https://bugzilla.mozilla.org/enter_bug.cgi?product=devtools Developer Tools bug] coordinating work with the DevTools team to build tools for this feature.<br />
''Link to standards-positions discussion'': Link to an issue in [https://github.com/mozilla/standards-positions/ mozilla/standards-positions] about what we think about the specification.<br />
''Other browsers'':
* Blink: address with "shipped" (since version X, behind what flags if any), "intent emailed" (mailing list URL), or "considering" (citation).
* WebKit: 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 ([https://github.com/w3c/web-platform-tests/issues/3867 example]).
* A spec issue for some change that would make it possible to test ([https://github.com/whatwg/fullscreen/issues/70 example]).
* A Bugzilla bug for the creating web-platform-tests.
</blockquote>
 
===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).
 
* ''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.
** +1 [[User:Tantek|Tantek]] ([https://tantek.com/ tantek.com]) 14:21, 12 August 2022 (UTC)
** ... add yourself
* ''Security & Privacy Concerns'': consider providing a link to answers in [https://mikewest.github.io/spec-questionnaire/security-privacy/ 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.
** +1 [[User:Tantek|Tantek]] ([https://tantek.com/ tantek.com]) 14:21, 12 August 2022 (UTC)
** ... add yourself
* ''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. E.g. a link to an https://webwewant.fyi/wants/ entry with that information.
** +1 [[User:Tantek|Tantek]] ([https://tantek.com/ tantek.com]) 14:21, 12 August 2022 (UTC)
** ... add yourself
* ''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.
** +1 [[User:Tantek|Tantek]] ([https://tantek.com/ tantek.com]) 14:21, 12 August 2022 (UTC)
** ... add yourself
 
==Intent to ship==
 
<blockquote>
'''To''': <tt>dev-platform@mozilla.org</tt><br />
'''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.
 
Standard: link to the standard; if the work is not yet part of a standard, also provide evidence that the responsible standards body has agreement that shipping the feature has broad support (see [[#Standardization requirements for shipping features|details above]])
 
This feature was previously discussed in this "Intent to prototype" thread:  <https://groups.google.com/a/mozilla.org/g/dev-platform>. '''If anything changed since that thread please include that information in this email'''.
</blockquote>
 
It's acceptable to merge the "intent to prototype" into the "intent to ship" email as long as all the relevant requirements are met.
 
===Suggested additions===
* ''TAG Review'': link to TAG review of the feature/spec. Note: Blink requires this in their intent process.
** +1 [[User:Zcorpan]] (proposed)
** +1 [[User:Tantek]]
** ... add yourself
 
=Removing features=
 
All removals require special care.  In particular, most removals have a [[Compatibility/WebPlatform|significant web compatibility risk]] that needs to be carefully assessed.
 
If you aim to remove a feature from the web, please follow these steps:
 
# [[#Changing or evolving features|Evaluate the removal]].
# Consult dev-platform with an [[#Intent to unship|intent to unship]] that includes any relevant 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.
# Unship the feature when all is in order.
 
==Intent to unship==
 
<blockquote>
'''To''': <tt>dev-platform@mozilla.org</tt><br />
'''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.>
</blockquote>
 
 
= See Also =
* [[WebAPI/WebIDL_Review_Checklist]]
* [https://www.chromium.org/blink Chrome/Blink change process]
** [https://www.chromium.org/blink/launching-features Chrome/Blink process for Launching Features] in particular
** [https://bit.ly/blink-signals Signals from other implementations]
* Intent To Ship bot: [https://botsin.space/@intenttoship Mastodon] [https://twitter.com/intenttoship Twitter] [https://github.com/autonome/intenttoship-bot Source code]
 
=FAQ=
 
==How do we know what web developers want?==
 
There's no good way to determine this currently, but feedback on GitHub, StackOverflow, workarounds in JavaScript libraries, MDN surveys, as well as use cases brought up during standardization help paint a picture.
 
==How do we know what other browser engines think?==
 
* Most of the time this should fall out of the standardization process (e.g., discussion in a GitHub repository)
* Watch for "intent to *" emails on mailing lists such as [https://groups.google.com/a/chromium.org/forum/#!forum/blink-dev blink-dev]
* By asking!
** WebKit (Apple) can be asked on their [https://github.com/WebKit/standards-positions standards-positions repo]
** Chrome: [https://source.chromium.org/chromium/chromium/src/+/main:docs/standards/positions/GoogleChrome/README.md Positions from Google Chrome Teams on Web Standards]
 
==How do we let other browser engines know what we think?==
 
* By documenting our position on [https://github.com/mozilla/standards-positions standards-positions].
* Participating in public discussions of new features.
* Comment on "Intent to *" threads on [https://groups.google.com/a/chromium.org/forum/#!forum/blink-dev blink-dev]. (Ideally this is not necessary, but it's a good last resort option.)
 
==What about prefixes?==
 
In the past, Mozilla has shipped experimental features with a "moz" prefix to indicate their lack of standardization (e.g., <code>mozRequestAnimationFrame()</code>). 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 [https://compat.spec.whatwg.org/ 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 [https://groups.google.com/forum/#!topic/mozilla.dev.platform/34JfwyEh5e4 Henri Sivonen's proposal]).
 
==Who decides?==
 
If the dev-platform thread results in a conflict, the respective [[Modules|module owner]] is responsible for resolving that conflict and making a decision on how to proceed.
 
== See Also ==
* [[Standards]]

Latest revision as of 19:21, 26 June 2023

Always ask: Is this good for the web?

Adding or changing features

This process applies to all code contributions to Firefox that introduce, modify, or remove features that change how the web platform operates.

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

  1. Evaluate the new feature or change to an existing features.
  2. Email dev-platform declaring your intent to prototype. (It is okay to skip this step for small changes*.)
  3. Implement as normal. Code review rounds will take place, web-platform-tests will be written, etc.
  4. Email dev-platform declaring your intent to ship on Firefox Release.
  5. If there's no negative feedback, ship it!

*If you’re not sure, it’s unlikely to be a small change.

New features

There’s a lot of nuance that goes into adding a feature to the web. Mozilla sets a high bar for any changes we make to the web.

Making new features available requires some care and consideration.

Establish that the feature is important

We have finite resources and we want to ensure that we develop features that are important. Reasons might include:

  • It’s of strategic importance to Mozilla.
  • It contributes to Mozilla’s mission.
  • This will make us the second/third browser to ship this, enabling more web developers to use it. That is, this helps with web compatibility and moves the web forward by having another independent implementation.

Ensure that the feature is standardized

Mozilla is committed to standardization as the basis for evolving the Web. We want to ensure that features are good for our users and have broad support from other browsers, web developers, and the broader community. The standards process is how we ensure that features meet these expectations.

Our goal is that all new web-facing features are based on a specification that is the product of a recognized standards body.

Standardization requirements for prototypes

If a specification for a feature is not the product of a standards body, your intent to prototype needs to identify what steps have been taken to ensure that it will be. You should identify which standards body you believe should take the work on. Include a link to a record from that standards body that tracks the feature becoming an official product.

What you minimally need to show might differ according to the processes of the standards body:

  • W3C - an issue raised on a working group charter (not a community group)
  • WHATWG - an issue raised on the appropriate standard(s)
  • IETF - an explicit request for adoption by a working group
  • TC39 - a link to a proposal at stage 1 or higher
  • For other bodies, a request for consideration according to the procedures of the body

Being able to prototype new features allows us to learn about them, but experimentation serves to inform our choices in standards bodies. Features that have not been discussed within the processes of a standards body will require extra scrutiny to ensure that it is safe to prototype. This applies especially to W3C work that is not the product of a working group or community group; the same applies to individual submissions to the IETF.

Standardization requirements for shipping features

An intent to ship must include an update on the standardization status of the feature. We expect that shipping features will be further advanced in the standards process when they ship.

Your intent to ship should include information that shows not only that the standards body has adopted the work, but also that there is consensus that the feature is ready to be shipped. What evidence is necessary will vary, but generally this will be:

  • W3C - the specification is at the Candidate Recommendation maturity level or more advanced; shipping from a Working Draft or a less advanced specification requires evidence of agreement within the working group that shipping is acceptable
  • WHATWG - the changes have been merged into a standard; an open pull request requires additional evidence of agreement among implementers that shipping is acceptable
  • IETF - a working group draft that has been passed to the IESG for publication by the working group; a draft working group in an earlier state should show evidence that shipping is acceptable to the working group
  • TC39 - the proposal is at stage 3 or higher
  • The product of other bodies will be assessed individually

In all of these cases, try to show that there are no significant unresolved issues with a specification and that there are no objections to shipping it. Simply showing that there is support for a feature is less useful.

Shipping features that don’t meet these requirements is still possible, including features that don't show broad agreement that shipping is acceptable. If your feature needs an exception to this rule, please reach out to Firefox Technical Leadership. Any intent regarding a non-standard feature might need to include additional safeguards such as experimentation and data collection plans, risk assessments, and rollback strategies.

Ensure that Mozilla has a position on the feature

standards-positions is where Mozilla formalizes positions on new features. Open an issue there if one does not already exist.

Changing or evolving features

When making changes to existing features or even removing existing features many of the considerations stated for evaluating new features apply, but one thing that is quite different is that telemetry might be important here as in general Mozilla is pretty averse to shipping breaking changes. Coordination with the relevant standard and other browsers is usually the way to go.


Email templates for new or changed features

When announcing your intent to prototype or ship a feature, using these templates ensures that you don’t miss anything critical.

Intent to prototype

To: dev-platform@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.
Specification: link to the specification (see details above)
Standards Body: identify the standards body responsible for standardizing this feature if that is not obvious from the specification; if the specification is not already adopted by a standards body, link to the issue or a discussion about adoption of the work (if no discussion exists, please start that process before filing this intent)
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.
Link to standards-positions discussion: Link to an issue in mozilla/standards-positions about what we think about the specification.
Other browsers:

  • Blink: address with "shipped" (since version X, behind what flags if any), "intent emailed" (mailing list URL), or "considering" (citation).
  • WebKit: 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).

  • 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. E.g. a link to an https://webwewant.fyi/wants/ entry with that information.
  • 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@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.

Standard: link to the standard; if the work is not yet part of a standard, also provide evidence that the responsible standards body has agreement that shipping the feature has broad support (see details above)

This feature was previously discussed in this "Intent to prototype" thread: <https://groups.google.com/a/mozilla.org/g/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.

Suggested additions

  • TAG Review: link to TAG review of the feature/spec. Note: Blink requires this in their intent process.

Removing features

All removals require special care. In particular, most removals have a significant web compatibility risk that needs to be carefully assessed.

If you aim to remove a feature from the web, please follow these steps:

  1. Evaluate the removal.
  2. Consult dev-platform with an intent to unship that includes any relevant data.
  3. 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.
  4. Unship the feature when all is in order.

Intent to unship

To: dev-platform@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

FAQ

How do we know what web developers want?

There's no good way to determine this currently, but feedback on GitHub, StackOverflow, workarounds in JavaScript libraries, MDN surveys, as well as use cases brought up during standardization help paint a picture.

How do we know what other browser engines think?

How do we let other browser engines know what we think?

  • By documenting our position on standards-positions.
  • Participating in public discussions of new features.
  • Comment on "Intent to *" threads on blink-dev. (Ideally this is not necessary, but it's a good last resort option.)

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

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.

See Also

Retrieved from "https://wiki.allizom.org/index.php?title=ExposureGuidelines&oldid=1246866"