Skip to content

Embellish discouraged data with more detail #3193

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

Draft
wants to merge 6 commits into
base: main
Choose a base branch
from
Draft

Embellish discouraged data with more detail #3193

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
f3e539e
Embellish `discouraged` data with more detail
ddbeck Jul 30, 2025
c312a78
Add discouragement reason to SVG 1.1
ddbeck Aug 14, 2025
18f1c79
Add discouraged embellishments to the schema
ddbeck Sep 4, 2025
3f2c60f
Merge branch 'main' into mock-discouraged-data
ddbeck Sep 11, 2025
4b53814
Convert `removal_expected_date` to `removal_date` for easier maintenance
ddbeck Sep 11, 2025
3acf733
Add more reasons
ddbeck Sep 11, 2025
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
1 change: 1 addition & 0 deletions features/accessor-methods.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@ name: Accessor methods
description: The `__defineGetter__()` and `__defineSetter__()` methods of objects bind a function to a property, which is called on setting or reading the property.
spec: https://tc39.es/ecma262/multipage/fundamental-objects.html#sec-object.prototype-legacy-accessor-methods
discouraged:
reason: TC39 included accessor methods in Annex B of the ECMAScript specification, which covers JavaScript features with "one or more undesirable characteristics and in the absence of legacy usage would be removed."
Copy link
Collaborator Author

Choose a reason for hiding this comment

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

I don't really know why this was stuffed into Annex B (the spec does not provide more specific text, unlike getYear(), so I just quote from the spec directly.

according_to:
- https://tc39.es/ecma262/multipage/additional-ecmascript-features-for-web-browsers.html#sec-additional-ecmascript-features-for-web-browsers
# No `alternatives` because it would be `alternatives:
Expand Down
1 change: 1 addition & 0 deletions features/arguments-callee.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ discouraged:
# From note 4: "The definition of this property […] exists to ensure that it
# is not defined in any other manner by conforming ECMAScript
# implementations."
reason: JavaScript strict mode prohibits accessing `arguments.callee`.
according_to:
- https://tc39.es/ecma262/multipage/ordinary-and-exotic-objects-behaviours.html#sec-arguments-exotic-objects
compat_features:
Expand Down
1 change: 1 addition & 0 deletions features/clip.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ description: The `clip` CSS property sets the visible area of an absolutely posi
spec: https://drafts.fxtf.org/css-masking-1/#clip-property
group: clipping-shapes-masking
discouraged:
reason: The CSS Masking specification deprecated the `clip` property.
according_to:
- https://drafts.fxtf.org/css-masking-1/#clip-property
alternatives:
Expand Down
1 change: 1 addition & 0 deletions features/color-adjust.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ description: The `color-adjust` shorthand CSS property allows multiple performan
spec: https://drafts.csswg.org/css-color-adjust-1/#color-adjust
group: print
discouraged:
reason: The CSS Color Adjustment specification described the `color-adjust` as deprecated, to prevent authors from accidentally resetting color adjustments in unexpected contexts.
according_to:
- https://drafts.csswg.org/css-color-adjust-1/#color-adjust
alternatives:
Expand Down
1 change: 1 addition & 0 deletions features/color-contrast.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ description: "The `color-contrast()` CSS function picks a color from a list that
spec: https://drafts.csswg.org/css-color-5/#contrast-color
group: color-types
discouraged:
reason: The CSS Color specification renamed `color-contrast()` to `contrast-color()`.
# See these CSSWG discussions
# https://github.com/w3c/csswg-drafts/issues/7557
# https://github.com/w3c/csswg-drafts/issues/7359
Expand Down
1 change: 1 addition & 0 deletions features/css-object-model-discouraged.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ description: The DOM level 2 style specification defined interfaces to access an
spec: https://www.w3.org/TR/DOM-Level-2-Style/
group: cssom
discouraged:
reason: The DOM level 2 CSS object model was excluded from the later CSS object model (CSSOM) specification.
according_to:
- https://www.w3.org/TR/DOM-Level-2-Style/#Overview-status
alternatives:
Expand Down
1 change: 1 addition & 0 deletions features/date-get-year-set-year.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ description: The `getYear()` and `setYear()` methods of `Date` objects get and s
spec: https://tc39.es/ecma262/multipage/additional-ecmascript-features-for-web-browsers.html#sec-date.prototype.getyear
group: javascript
discouraged:
reason: The `getYear()` and `setYear()` methods use a truncated number instead of the actual year number, known as a year 2000 problem.
according_to:
- https://tc39.es/ecma262/multipage/additional-ecmascript-features-for-web-browsers.html#sec-additional-ecmascript-features-for-web-browsers
# No `alternatives` because it would be `alternatives: [date]`. In the future
Expand Down
3 changes: 3 additions & 0 deletions features/mutation-events.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,11 @@ description: Mutation events like `DOMSubtreeModified`, `DOMNodeInserted`, or `D
spec: https://w3c.github.io/uievents/
group: dom
discouraged:
pending_removal: true
Copy link
Collaborator Author

Choose a reason for hiding this comment

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

Here's our one removal pending. All pending removal features are discouraged features, but not all discouraged features are pending removal, thus a subordinate key and value here.

Copy link
Contributor

Choose a reason for hiding this comment

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

Have we talked about what happens once features are removed? Will we then delete the mutation-events.yml file and dist file? I suspect not, since we likely don't want to reuse the ID.

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

We have not, though perhaps we should do so at the same time. My (very briefly considered) guess is that we ought to have some feature-level annotation that says, more or less, "this is historic and you should not show it to developers by default." It would cover both features removed (like this one) but also features that never shipped widely in the first place (import-assertions would be a good example) or got abandoned before making it into a stable release.

Maybe something like retired: true, but I'm reluctant to add a single-use boolean. Something "stringy" would be nice, so we have the option of introducing nuance later, if needed. Maybe a sort of summary field? condition: "normal" | "discouraged" | "pending-removal" | "historic". We'll need to think on this problem a little more.

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

After some discussion with MDN, it occurred to me that instead of a boolean, we could have something like removal_scheduled_date: 2025-12-31. The presence of this field could indicate that removal is pending as well as when we expect it to be removed.

MDN also suggested that the reason field contain a removal timeline in the case of pending removal features.

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

After writing reason fields for everything, I thought it would be easier to create and maintain this data if it were a removal_date that is either a future date (the expected timeline for removal) or today or a past date (for when it was actually removed). This would make maintaining the data a bit more straightforward: once the feature is gone, we don't have to go and remove data.

reason: Mutation events negatively impact performance and they were selected for removal from the web as part of Interop 2025.
according_to:
- https://www.w3.org/TR/2024/WD-uievents-20240906/#legacy-mutationevent-events
- https://github.com/web-platform-tests/interop/issues/784
alternatives:
- mutationobserver
compat_features:
Expand Down
3 changes: 2 additions & 1 deletion features/svg-discouraged.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,10 @@
name: SVG 1.1 (discouraged)
name: SVG 1.1
description: The SVG 1.1 image format has several components that were excluded from SVG 2, such as fonts, alternate glyphs, and the `xlink` namespace.
spec: https://www.w3.org/TR/SVG11/
discouraged:
according_to:
- https://svgwg.org/svg2-draft/changes.html#substantial
reason: SVG 2 omittted some parts of SVG 1.1 to "improv[e] the usability and precision of the language."
alternatives:
- svg
- font-face
Expand Down
Loading