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

Jump to bottom

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 2 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
104 changes: 100 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,105 @@ 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

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

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">Deprecated from</dfn></th>
<th><dfn for="deprecated feature list">Removal</dfn></th>
<th><dfn for="deprecated feature list">Replacement</dfn></th>
<th><dfn for="deprecated feature list">Justification</dfn></th>
<th><dfn for="deprecated feature list">Automated Tools</dfn></th>
Copy link
Member

Choose a reason for hiding this comment

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

As noted in some previous comments, it seems like we'll be cramming a lot of information into this horizontal table. I wonder if it would be reasonable to either:

  • Simplify the table by dropping the last three columns, and instead requiring an explainer link (that presumably would contain this information). Or,
  • Change the table into a more vertical structure. Just bulleted lists with relevant text?

Copy link
Author

Choose a reason for hiding this comment

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

I think the first option is a bit better, if only to give information "at a glance". I envisioned justification as a link somewhere anyway, so some suggestion of what content is most important would be a reasonable substitute.

<tr>
</thead>
<tbody>
<tr>
</tr>
</tbody>
</table>

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

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

Choose a reason for hiding this comment

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

This suggests we might end up with a bunch of engine/product specific deprecations... is that what we want? Or are we trying to cover deprecations/removals that fit the spirit of WHATWG, where there is alignment of at least 2 engines?

If we do want to cover engine-specific stuff, maybe a separate table for that? Experimental deprecations or something.

Copy link
Author

Choose a reason for hiding this comment

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

I think there are two relevant ideas here:

  1. This is meant to be stuff in the spirit of WHATWG.
  2. Since it has concrete stuff about the browser's future plans and anyone can write a PR we probably want to be careful about getting all the right contexts in reviewing it. I gated that on the editor's discretion.

Copy link
Member

Choose a reason for hiding this comment

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

A potential path forward would be to move towards a general practice for folks to file issues against the spec to add deprecations, use those as a forum for alignment between engines, and land them in the spec when there's broader agreement on the direction.

If we want a more holistic list with a lower bar for entry, perhaps a wiki page or something similarly unofficial and light-weight would be appropriate?

Copy link
Author

Choose a reason for hiding this comment

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

A potential path forward would be to move towards a general practice for folks to file issues against the spec to add deprecations, use those as a forum for alignment between engines, and land them in the spec when there's broader agreement on the direction.

I think this is a good idea, and I'd be happy to make the contents of this document represent consensus, with PRs being a good place for discussion.

their discretion in what reviewers are appropriate for a given change to the list.
Copy link
Member

Choose a reason for hiding this comment

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

We should probably discuss this as well - having multiple reviewers is good (especially from folks with the right context) - but we still have a single editor for this standard. We could explore "deputy editors" per https://whatwg.org/working-mode#editor - or come up with an agreement of when things are ready to be merged (solving the single- vs multi-implementer comment above will probs help here).

Copy link
Author

Choose a reason for hiding this comment

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

This is the bit I was trying to get at. I think an agreement of when things are ready to be merged may be sufficient, given a responsible editor. :)

Figuring out when merging a row in the table is "not writing fiction" is probably the hard bit. Perhaps that is a kernel that needs a good answer.

[[#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:

<ul>
<li>the [=deprecated feature list/Feature | feature or behavior=] that is being removed or deprecated.
<li>what browser engines have [=deprecated feature list/Deprecated from | deprecated =] the feature or behavior, discouraging its further use.
<li>when the feature will be, or has been, [=deprecated feature list/Removal | removed =] from various browser engines, preventing its use by default.
<li>what developers should use to achieve the same functional goals, as a [=deprecated feature list/Replacement | replacement =] for the old feature.
<li>[=deprecated feature list/ | justification =] for the removal or deprecation, including any tradeoffs considered and steps taken to minimize disruption to developers.
bvandersloot-mozilla marked this conversation as resolved.
Show resolved Hide resolved
<li>links to any [=deprecated feature list/Automated Tools | automated tools =] to assist developers, such as detection or migration scripts.
</ul>

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

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.

<h3 id="removal-support">Supporting information</h3>

<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
Loading