Add a new section for information about prospective deprecations and removals #271
Conversation
There was a problem hiding this comment.
I wonder if this should describe some of the criteria.
See also https://whatwg.org/working-mode#removals.
| <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 |
There was a problem hiding this comment.
The table only seems to allow for removal, not discouragement. Should we document synchronous XMLHttpRequest?
There was a problem hiding this comment.
I'd consider an entry with Removal empty, but Deprecated from not empty to be discouraged.
A definition would be useful to clarify that
I agree that criteria would be useful, and at very least a link to removals is required here. There are two levels of criteria I could see trying to include, logistics focused (like the working mode docs describe, trying to reflect reality) or descriptive ("here are the things we think you should consider before you add it to this list", like the artifact from the breakout gets at). Which did you mean? |
bvandersloot-mozilla
force-pushed
the
bvandersloot-deprecation
branch
from
e9b419e
to
4480713
Compare
|
I was thinking about the descriptive kind as the Working Mode indeed already takes care of the other bits. The bar needs to be high and I think clarifying that upfront will help. |
compatibility.bs
Outdated
| <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. |
There was a problem hiding this comment.
This feels like it could span anywhere from a sentence to a multi-page document... that may get awkward and unreadable in an HTML table. Maybe a link to a different resource like an Intent to Deprecate from blink-dev or gecko-dev, or a WebKit blog post, etc? Or just a design doc or spec issue. 🤷
There was a problem hiding this comment.
I was imagining a link to a dedicated subsection of Supporting Information. Spec issue or ItD links would also be fine. Honestly, just having a paragraph or two where the PR author commits to "why this needs to happen and what I did to make it hurt devs less" is my goal here.
compatibility.bs
Outdated
| <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 |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
I think there are two relevant ideas here:
- This is meant to be stuff in the spirit of WHATWG.
- 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.
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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.
compatibility.bs
Outdated
|
|
||
| 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. |
There was a problem hiding this comment.
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).
There was a problem hiding this comment.
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.
compatibility.bs
Outdated
| <li>links to any [=deprecated feature list/Automated Tools | automated tools =] to assist developers, such as detection or migration scripts. | ||
| </ul> | ||
|
|
||
| <h3 id="removal-support">Supporting Information</h3> |
There was a problem hiding this comment.
Subsections containing justifications for each deprecation? linked to from the table.
I'm happy to remove if this isn't needed.
bvandersloot-mozilla
force-pushed
the
bvandersloot-deprecation
branch
from
4480713
to
8a164e4
Compare
I added a section that captures some of the thoughts from the breakout. I am uncertain if it makes the PR better or worse, so I'd appreciate your feedback |
| 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. |
There was a problem hiding this comment.
| 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. |
compatibility.bs
Outdated
| <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 |
There was a problem hiding this comment.
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?
compatibility.bs
Outdated
| <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> |
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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.
…to make this easier
This is an addition that tries to create a point for further communication about deprecation and removal of web features, as we determined may be useful at TPAC in the deprecation breakout. Adding criteria for removal is out of scope; this is just adding a harm reduction mechanism and improve inter-browser and developer communication.
Feedback very welcome!
Folks that have expressed interest in this followup to me: @miketaylr @mikewest @RByers @alanbuxey @gregwhitworth @sysrqb @karlcow @ammedina88 @ayuishii @rachelandrew
Preview | Diff