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 1 commit into
base: main
Choose a base branch
from
Draft

Embellish discouraged data with more detail #3193

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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.

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
Loading