Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add a new section for information about prospective deprecations and removals #271

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Add a new section for information about prospective deprecations and removals #271

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
9d2dcad
Follow up from TPAC deprecation breakout, new section for information
bvandersloot-mozilla Oct 8, 2024
8a164e4
Adding critieria along Anne's suggestion
bvandersloot-mozilla Oct 9, 2024
39baa2e
Make the table normative and less detailed. Lean on the working mode …
bvandersloot-mozilla Oct 15, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
101 changes: 97 additions & 4 deletions compatibility.bs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -89,6 +89,8 @@ specified elsewhere.

The HTTP <code>User-Agent</code> header field as found in major browsers today is also described.

The removals of some features from the web platform are also described.

<h2 id='conformance'>Conformance</h2>
All diagrams, examples, and notes in this specification are
non-normative, as are all sections explicitly marked non-normative.
Expand Down Expand Up @@ -1055,11 +1057,102 @@ On mobile platforms, including smaller iPad form factors
</tbody>
</table>


<h2 id="removal">Deprecation and Removal</h2>
miketaylr marked this conversation as resolved.
Show resolved Hide resolved

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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The table only seems to allow for removal, not discouragement. Should we document synchronous XMLHttpRequest?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd consider an entry with Removal empty, but Deprecated from not empty to be discouraged.

A definition would be useful to clarify that

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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
beneficial as a decalration of intent by browser engines to act together in a well reasoned way.
beneficial as a declaration of intent by browser engines to act together in a well reasoned way.


<h3 id="removal-features">Feature List</h3>
bvandersloot-mozilla marked this conversation as resolved.
Show resolved Hide resolved

<table>
<thead>
<tr>
<th><dfn for="deprecated feature list">Feature</dfn></th>
<th><dfn for="deprecated feature list">Deprecation</dfn></th>
<th><dfn for="deprecated feature list">Removal</dfn></th>
<th><dfn for="deprecated feature list">More Information</dfn></th>
<tr>
</thead>
<tbody>
<tr>
</tr>
</tbody>
</table>

<h4 id="removal-features-process">Process</h4>

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 <a href="https://whatwg.org/working-mode">WHATWG Working Mode</a>, adding
a row to this table is a <a href="https://whatwg.org/working-mode#removals">removal</a>.

Note: [[#removal-criteria]] provides suggested criteria to consider when deciding if it is appropriate
to remove the feature to the web.

Each entry should include:

<ul>
<li>the [=deprecated feature list/Feature|feature or behavior=] that is being removed or deprecated.
<li>what browser engines have [=deprecated feature list/Deprecation|deprecated=] the feature or behavior, discouraging its further use.
<li>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.
<li>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.
</ul>

<h3 id="removal-criteria">Criteria for removal or deprecation</h3>

<em>This section is non-normative.</em>

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 <a href="https://whatwg.org/working-mode#removals">WHATWG Working Mode</a> 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:

<ul>
<li>User-visible breakage of any site is a harm worth considering
<li>The full set of use-cases for a feature can not be known, so unexpected things may break
<li>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
<li>Removal of features can disrupt ecosystems built on the web, changing their economics and incentives, and this is not always for the better
</ul>

Benefits of removing the feature are good reasons to proceed:

<ul>
<li>Security improvement
<li>Privacy and user protections improvement
<li>Accessibility improvement
<li>Platform architectural improvement
</ul>

Harms of removing the feature may be mitigated by some choices:

<ul>
<li>Lead time from deprecation to removal
<li>On-by-default, but easily disabled for a site by developers during the deprecation
<li>Coherence of action by browsers
<li>Mechanisms for site-specific workarounds controlled by the browser
<li>Strong, interoperable alternatives to the feature
<li>Younger and less-stable APIs are less ossified and are likely used by developers more apt to fix their website
</ul>

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.

<h2 id="acknowledgements" class="no-num">Acknowledgements</h2>
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]]
Expand Down