From 9d2dcada4f8581e9aa344490c020854a83de81fb Mon Sep 17 00:00:00 2001 From: Benjamin VanderSloot Date: Tue, 8 Oct 2024 09:20:38 -0400 Subject: [PATCH 1/3] Follow up from TPAC deprecation breakout, new section for information --- compatibility.bs | 60 ++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 56 insertions(+), 4 deletions(-) diff --git a/compatibility.bs b/compatibility.bs index 3bda92d..ecc0fed 100644 --- a/compatibility.bs +++ b/compatibility.bs @@ -89,6 +89,8 @@ specified elsewhere. The HTTP User-Agent header field as found in major browsers today is also described. +The removals of some features from the web platform are also described. +

Conformance

All diagrams, examples, and notes in this specification are non-normative, as are all sections explicitly marked non-normative. @@ -1055,11 +1057,61 @@ On mobile platforms, including smaller iPad form factors + +

Deprecation and Removal

+ +This section is non-normative. + +While the web platform stives for backwards-compatibility, there are occasions which require the +outright removal or discouraged use of some features. To support making these changes +in the least disruptive and most consistent way for developers, we document them here. This is most +beneficial as a decalration of intent by browser engines to act together in a well reasoned way. + +

Feature List

+ + + + + + + + + + + + + + + + +
FeatureDeprecated fromRemovalReplacementJustificationAutomated Tools
+ +

Process

+ +Anyone can make an addition to the list by editing this specification. +However, because some content describes the future plans of browser engines, the author can use +their discretion in what reviewers are appropriate for a given change to the list. +[[#removal-support]] is provided to give a place to link to long-form content within this +document for list entries. + +Each entry can include: + + + +

Supporting Information

+

Acknowledgements

-Thanks to Alan Cutter, Cameron McCormack, Chris Rebert, Chun-Min (Jeremy) Chen, Daniel Holbert, -David Håsäther, Domenic Denicola, Eric Portis, hexalys, Jean-Yves Perrier, Jacob Rossi, Karl Dubost, -Philip Jägenstedt, Rick Byers, Simon Pieters, Stanley Stuart, William Chen and Your Name Here for -feedback and contributions to this standard. +Thanks to Alan Cutter, Benjamin VanderSloot, Cameron McCormack, Chris Rebert, Chun-Min (Jeremy) Chen, +Daniel Holbert,David Håsäther, Domenic Denicola, Eric Portis, hexalys, Jean-Yves Perrier, Jacob Rossi, +Karl Dubost, Philip Jägenstedt, Rick Byers, Simon Pieters, Stanley Stuart, William Chen and +Your Name Here for feedback and contributions to this standard. Thanks to Mounir Lamouri and Marcos Cáceres for defining the {{ScreenOrientation}} interface. [[!screen-orientation]] From 8a164e4263c054ec5a8671ad7105799adc835758 Mon Sep 17 00:00:00 2001 From: Benjamin VanderSloot Date: Wed, 9 Oct 2024 15:02:59 -0400 Subject: [PATCH 2/3] Adding critieria along Anne's suggestion --- compatibility.bs | 52 ++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 48 insertions(+), 4 deletions(-) diff --git a/compatibility.bs b/compatibility.bs index ecc0fed..3c1634f 100644 --- a/compatibility.bs +++ b/compatibility.bs @@ -1091,8 +1091,9 @@ beneficial as a decalration of intent by browser engines to act together in a we Anyone can make an addition to the list by editing this specification. However, because some content describes the future plans of browser engines, the author can use their discretion in what reviewers are appropriate for a given change to the list. -[[#removal-support]] is provided to give a place to link to long-form content within this -document for list entries. +[[#removal-criteria]] provides suggested criteria to consider when deciding if it is appropriate +to remove the feature to the web. [[#removal-support]] provides to give a place to link to +long-form content within this document for list entries. Each entry can include: @@ -1105,11 +1106,54 @@ Each entry can include:
  • links to any [=deprecated feature list/Automated Tools | automated tools =] to assist developers, such as detection or migration scripts. -

    Supporting Information

    +

    Criteria for removal or deprecation

    + +The bar to make a breaking change in the web platform across multiple browser engines can be high. +This is a good thing, as the web should strive for backward compatibility as much as is possible. +The WHATWG Working Mode even establishes +further requirements for changes to specifications that remove behavior. This section provides an +incomplete enumeration of criteria that should be considered before including a feature in the +[[Feature List]]. This is not an algorithm to decide what can be removed; each feature removal is +unique and requires the careful decision making of the implementers to weigh the costs and benefits +of proceeding with removal. + +Harms of removing the feature are good reasons to not proceed: + +
      +
    • User-visible breakage of any site is a harm worth considering +
    • The full set of use-cases for a feature can not be known, so unexpected things may break +
    • Removal of features has an outsized influence on smaller development operations that have fewer resources for maintanance and can not track the changes to the web platform closely +
    • Removal of features can disrupt ecosystems built on the web, changing their economics and incentives, and this is not always for the better +
    + +Benefits of removing the feature are good reasons to proceed: + +
      +
    • Security improvement +
    • Privacy and user protections improvement +
    • Accessibility improvement +
    • Platform architectural improvement +
    + +Harms of removing the feature may be mitigated by some choices: + +
      +
    • Lead time from deprecation to removal +
    • On-by-default, but easily disabled for a site by developers during the deprecation +
    • Coherence of action by browsers +
    • Mechanisms for site-specific workarounds controlled by the browser +
    • Strong, interoperable alternatives to the feature +
    • Younger and less-stable APIs are less ossified and are likely used by developers more apt to fix their website +
    + +It is important to note that any alternatives to the feature will face the same scrutiny when they are to be removed, +deferring the issue of breakage rather than resolving it. + +

    Supporting information

    Acknowledgements

    Thanks to Alan Cutter, Benjamin VanderSloot, Cameron McCormack, Chris Rebert, Chun-Min (Jeremy) Chen, -Daniel Holbert,David Håsäther, Domenic Denicola, Eric Portis, hexalys, Jean-Yves Perrier, Jacob Rossi, +Daniel Holbert, David Håsäther, Domenic Denicola, Eric Portis, hexalys, Jean-Yves Perrier, Jacob Rossi, Karl Dubost, Philip Jägenstedt, Rick Byers, Simon Pieters, Stanley Stuart, William Chen and Your Name Here for feedback and contributions to this standard. From 39baa2e45fef0bba5d25bcae29fd2188d5d86c03 Mon Sep 17 00:00:00 2001 From: Benjamin VanderSloot Date: Tue, 15 Oct 2024 13:53:57 -0400 Subject: [PATCH 3/3] Make the table normative and less detailed. Lean on the working mode to make this easier --- compatibility.bs | 39 ++++++++++++++++++--------------------- 1 file changed, 18 insertions(+), 21 deletions(-) diff --git a/compatibility.bs b/compatibility.bs index 3c1634f..86f5b11 100644 --- a/compatibility.bs +++ b/compatibility.bs @@ -1060,8 +1060,6 @@ On mobile platforms, including smaller iPad form factors

    Deprecation and Removal

    -This section is non-normative. - While the web platform stives for backwards-compatibility, there are occasions which require the outright removal or discouraged use of some features. To support making these changes in the least disruptive and most consistent way for developers, we document them here. This is most @@ -1073,11 +1071,9 @@ beneficial as a decalration of intent by browser engines to act together in a we Feature - Deprecated from + Deprecation Removal - Replacement - Justification - Automated Tools + More Information @@ -1088,26 +1084,29 @@ beneficial as a decalration of intent by browser engines to act together in a we

    Process

    -Anyone can make an addition to the list by editing this specification. -However, because some content describes the future plans of browser engines, the author can use -their discretion in what reviewers are appropriate for a given change to the list. -[[#removal-criteria]] provides suggested criteria to consider when deciding if it is appropriate -to remove the feature to the web. [[#removal-support]] provides to give a place to link to -long-form content within this document for list entries. +Anyone may suggest an addition to the list by filing an issue on this specification. Each added row +that includes [=deprecated feature list/Removal|removal information=] should correspond to a normative +change in the specification that defined this behavior before its removal. + +Note: For sake of the WHATWG Working Mode, adding +a row to this table is a removal. + +Note: [[#removal-criteria]] provides suggested criteria to consider when deciding if it is appropriate +to remove the feature to the web. -Each entry can include: +Each entry should include:
      -
    • the [=deprecated feature list/Feature | feature or behavior=] that is being removed or deprecated. -
    • what browser engines have [=deprecated feature list/Deprecated from | deprecated =] the feature or behavior, discouraging its further use. -
    • when the feature will be, or has been, [=deprecated feature list/Removal | removed =] from various browser engines, preventing its use by default. -
    • what developers should use to achieve the same functional goals, as a [=deprecated feature list/Replacement | replacement =] for the old feature. -
    • [=deprecated feature list/ | justification =] for the removal or deprecation, including any tradeoffs considered and steps taken to minimize disruption to developers. -
    • links to any [=deprecated feature list/Automated Tools | automated tools =] to assist developers, such as detection or migration scripts. +
    • the [=deprecated feature list/Feature|feature or behavior=] that is being removed or deprecated. +
    • what browser engines have [=deprecated feature list/Deprecation|deprecated=] the feature or behavior, discouraging its further use. +
    • when the feature will be, or has been, [=deprecated feature list/Removal|removed=] from browser engines, preventing its use by default. This may be empty if there is no such plan. +
    • a link to non-normative [=deprecated feature list/More Information|more information=] about the removal, such as justification for the removal, alternatives to use, or automated tools to improve developer experience.

    Criteria for removal or deprecation

    +This section is non-normative. + The bar to make a breaking change in the web platform across multiple browser engines can be high. This is a good thing, as the web should strive for backward compatibility as much as is possible. The WHATWG Working Mode even establishes @@ -1149,8 +1148,6 @@ Harms of removing the feature may be mitigated by some choices: It is important to note that any alternatives to the feature will face the same scrutiny when they are to be removed, deferring the issue of breakage rather than resolving it. -

    Supporting information

    -

    Acknowledgements

    Thanks to Alan Cutter, Benjamin VanderSloot, Cameron McCormack, Chris Rebert, Chun-Min (Jeremy) Chen, Daniel Holbert, David Håsäther, Domenic Denicola, Eric Portis, hexalys, Jean-Yves Perrier, Jacob Rossi,