ExposureGuidelines: Difference between revisions

ExposureGuidelines (view source)

Revision as of 10:05, 1 July 2019

2,163 bytes removed , 1 July 2019

Restructure this page significantly to put the more relevant information higher up and have somewhat less duplication (also remove "intent to implement and ship" as that can just be "intent to ship")

Annevk

Confirmed users

112

edits

@@ Line 1: / Line 1: @@
-=Guiding Principles=
+=Adding features=
-Mozilla aims to advance the state of the web platform with new features. In past years, 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 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]).
-We will instead make experimental features available behind preferences which can be toggled through <code>about:config</code>. 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.
+One way Mozilla aims to advance the state of the web platform is with new features. Always ask: ''Is this good for the web?''
-==Special Cases==
+If you aim to expose a new feature to the web or change an existing feature, please follow the steps below. Note that trivial changes might not need to worry about this.
-There may be special cases where we deviate from this goal. New user-facing products may need to ship features that have not yet been embraced by other browser engines or thoroughly discussed by standards bodies. This allows Mozilla to provide functionality that other browser engines aren't working on or the majority of the Web community isn't interested in at that time. We will avoid exposing such functionality to the web at large. Developing these features without much involvement from the Web community comes with the price of temporary proprietary features. This clearly indicates their lack of standardization at that time and limits the number of developers relying upon them. Mozilla will learn from such efforts and use this knowledge to inform various standardization efforts. Our aim is to standardize our proprietary features as soon as possible so they become available on a royalty-free basis for the benefit of the web community at large.
-=Guidelines for Mozillians developing new features=
+# Email [https://lists.mozilla.org/listinfo/dev-platform dev-platform] declaring your [[#Intent to implement|intent to implement]] or [[#Intent to ship|intent to ship]].  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 [http://www.w3.org/2005/10/Process-20051014/tr#q74 W3C CR status] if possible).
-The following is put forward as a set of guidelines for Mozillians -- especially [[Modules|module owners and peers]] -- to refer to while developing new APIs for the Web.  The primary question that must be asked is:
-::''Is this good for the web?''
-If the answer to that question is yes, look below for some guidance on how you should proceed with shipping your new feature. Note that trivial changes need not worry about these suggested guidelines.
-==When is an feature ready to be shipped by Gecko?==
-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:
-# other browser engines ship compatible implementations in their releases or behind a preference with clear signals it will graduate to being on by default
-# other browser engines state their ''intention'' to ship a compatible implementation
-# a large number of web developers indicate their satisfaction with the feature design
-# 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 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 implement" emails on mailing lists such as [https://groups.google.com/a/chromium.org/forum/#!forum/blink-dev blink-dev]
-* 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 know what web developers want?==
-* Mozilla's [[Engagement/Developer_Engagement|Developer Engagement]] coordinates a [https://openwebapps.uservoice.com/forums/258478-open-web-apps Open Web Apps UserVoice] forum
-* [http://chromestatus.com chromestatus.com] has a column for new features entitled "Documented or perceived web developer views"
-==How do we let other browser engines know what we think?==
-* participate in public discussions of proposed features
-* blog and/or tweet about proposed features
-* comment on "intent to implement" threads on [https://groups.google.com/a/chromium.org/forum/#!forum/blink-dev blink-dev]
-==Suggested implementation process==
-If your work is going to expose a new feature to the web or non-trivially change an existing one, it is requested that you follow these steps:
-# Email [https://lists.mozilla.org/listinfo/dev-platform dev-platform] declaring your [[#Intent to Implement|intent to implement]].  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 [http://www.w3.org/2005/10/Process-20051014/tr#q74 W3C CR status] if possible).
 # 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.
 # [https://blog.mozilla.org/security/2018/01/15/secure-contexts-everywhere/ Restrict the feature to secure contexts].
@@ Line 46: / Line 11: @@
 # Land potentially disruptive features behind a preference which is off by default.
-==Turning a preference on by default==
+==Intent to implement==
-When you are satisfied that your new feature is stable enough for exposure to the web at large (see [[#When is a feature ready to be shipped by Gecko?|above]]), it is requested that implementers send another email to dev-platform declaring their [[#Intent to ship|intent to ship]].  Among other things, this email serves to inform those that are interested in the new API but have not been closely following the implementation bug(s).
-=Guidelines for 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.
-=Decision making=
-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.
-=Email templates=
-==Intent to implement==
 '''To''': <tt>dev-platform@lists.mozilla.org</tt><br />
 '''Subject''': Intent to implement: <your feature goes here>
-''Summary'': [https://en.wikipedia.org/wiki/Elevator_pitch elevator pitch] for the new functionality including benefits to web developers<br />
+''Summary'': [https://en.wikipedia.org/wiki/Elevator_pitch elevator pitch] for the new functionality including benefits to web developers.<br />
-''Bug'': link to main implementation tracking bug<br />
+''Bug'': link to Bugzilla (tracking) bug.<br />
-''Link to standard'': if no formal specification exists yet, link to public discussions with other browser vendors<br />
+''Standard'': link to standard or link to public discussions with other browser vendors.<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 />
+''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 />
-''Estimated or target release'': in which version do you want to/plan to release this?<br />
+''Preference'': if applicable, how can interested parties test this before it ships pref'd on by default?<br />
-''Preference behind which this will be implemented'':  if applicable, how can interested parties test this before it ships pref'd on by default?<br />
-''Is this feature enabled by default in sandboxed iframes?'' If not, is there a proposed sandbox flag to enable it?  If allowed, does it preserve the current invariants in terms of what sandboxed iframes can do?<br/>
 ''DevTools bug'': link to a [https://bugzilla.mozilla.org/enter_bug.cgi?product=Firefox&component=Developer%20Tools Firefox :: Developer Tools bug] coordinating work with the DevTools team to build tools for this feature.<br />
-''Do other browser engines implement this?'' Answer with: shipped (since version X, behind what flags if any); intent to implement emailed (mailing list URL); considering (citation).<br />
+''Other browsers'': address with shipped (since version X, behind what flags if any), intent to implement emailed (mailing list URL), or considering (citation).<br />
 ''web-platform-tests'': Please link to the test suite. If any part of the feature is not tested by web-platform-tests, 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.
-''Is this feature restricted to secure contexts?'' Provide justification if this feature is not restricted to secure contexts. Otherwise, use "Yes".
+''Secure contexts'': Provide justification if this feature is not restricted to secure contexts. Otherwise, use "Yes".
+''Is this feature enabled by default in sandboxed iframes?'' If not, is there a proposed sandbox flag to enable it? If allowed, does it preserve the current invariants in terms of what sandboxed iframes can do?<br/>
+===Suggested additions===
-=== Suggested additions ===
 The above is the minimum required that should be in an "Intent to implement" email. If you've covered those, you're good, and brevity is a virtue.
@@ Line 97: / Line 42: @@
 ==Intent to ship==
 '''To''': <tt>dev-platform@lists.mozilla.org</tt><br />
 '''Subject''': Intent to ship: <your feature goes here>
@@ Line 104: / Line 50: @@
 ''Bug to turn on by default'':  link to main relevant bug (https://bugzilla.mozilla.org/show_bug.cgi?id=) ['''note''': this bug should ideally have the ''dev-doc-needed'' keyword set]<br />
-This feature was previously discussed in this "intent to implement" thread:  <https://groups.google.com/forum/#!forum/mozilla.dev.platform>. '''If anything changed since that thread please include that information in this email'''.
+This feature was previously discussed in this "Intent to implement" 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 implement" into the "intent to ship" email as long as all the relevant requirements are met.
-==Intent to implement and ship==
-'''To''': <tt>dev-platform@lists.mozilla.org</tt><br />
-'''Subject''': Intent to implement and ship: <your feature goes here>
-It's acceptable to combine the "intent to implement" and "intent to ship" emails 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|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==
@@ Line 125: / Line 78: @@
 * [https://www.chromium.org/blink Chrome/Blink change process]
 ** [https://www.chromium.org/blink/launching-features 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:
+# other browser engines ship compatible implementations in their releases or behind a preference with clear signals it will graduate to being on by default
+# other browser engines state their ''intention'' to ship a compatible implementation
+# a large number of web developers indicate their satisfaction with the feature design
+# 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 [[Engagement/Developer_Engagement|Developer Engagement]] coordinates a [https://openwebapps.uservoice.com/forums/258478-open-web-apps Open Web Apps UserVoice] forum
+* [http://chromestatus.com 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 implement" emails on mailing lists such as [https://groups.google.com/a/chromium.org/forum/#!forum/blink-dev blink-dev]
+* 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 implement" threads on [https://groups.google.com/a/chromium.org/forum/#!forum/blink-dev 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., <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]).
+We will instead prototype features behind preferences which can be toggled through <code>about:config</code>. 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 [[Modules|module owner]] is responsible for resolving that conflict and making a decision on how to proceed.