User:Mthomson/ExposureGuidelines2022: Difference between revisions

From MozillaWiki
Jump to navigation Jump to search
(Create a copy of ExposureGuidelines for drafting)
 
(Delete it)
 
(10 intermediate revisions by the same user not shown)
Line 1: Line 1:
'''Always ask: ''Is this good for the web?'''''


=Adding or changing features=
If you aim to expose a new feature to the web or change an existing feature, please follow these steps:
# [[#Evaluating new features|Evaluate the new feature]] or [[#Evaluating changes|change to an existing features]].
# 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!
==Evaluating new features==
There’s a lot of nuance that goes into adding a feature to the web. These questions will help to evaluate if it is worth doing and what it takes to do it.
===Why is the feature important?===
Given that we only have a finite amount of time, why are we pursuing this? For example:
* It’s of strategic importance to Mozilla.
* This will make us the second/third browser to ship this enabling more web developers to use it. I.e., this helps with web compatibility and moves the web forward by having another independent implementation.
===Is the feature covered by a specification?===
New features in Gecko should meet these requirements:
* There should be a specification that describes the feature that is adopted by a standards group that intends to produce a standard out of it.
* That group should consider the specification to be sufficiently stable.
Mozilla sets a relatively high bar for any changes we make to the web to ensure there is broad support. I.e., non-WG IETF drafts (shortname does not start with draft-ietf) or drafts from W3C CGs do not count.
If your feature needs an exception to this rule, please reach out to [[Modules/Firefox_Technical_Leadership|Firefox Technical Leadership]].
===Does Mozilla have a position on the feature?===
If you are unsure whether the feature has broader support within Mozilla, [https://github.com/mozilla/standards-positions standards-positions] is a useful way of determining that.
==Evaluating changes==
When making changes to existing features or even removing existing features many of the considerations stated for [[#Evaluating 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.
==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 />
''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 />
''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 />
''Other browsers'': address with "shipped" (since version X, behind what flags if any), "intent 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, 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).
* ''Link to standards-positions discussion'': Link to a discussion in [https://github.com/mozilla/standards-positions 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 [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.
* ''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==
<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.
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'''.
</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.
=Removing features=
If you aim to remove a feature from the web, please follow these steps:
# [[#Evaluating changes|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
=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!
==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.

Latest revision as of 04:29, 11 March 2022

Retrieved from "https://wiki.mozilla.org/index.php?title=User:Mthomson/ExposureGuidelines2022&oldid=1241161"