From f3e539e1224283dee7d72949fbf011fc4ecff6ec Mon Sep 17 00:00:00 2001 From: "Daniel D. Beck" Date: Wed, 30 Jul 2025 16:13:40 +0200 Subject: [PATCH 1/5] Embellish `discouraged` data with more detail --- features/accessor-methods.yml | 1 + features/arguments-callee.yml | 1 + features/clip.yml | 1 + features/color-adjust.yml | 1 + features/color-contrast.yml | 1 + features/css-object-model-discouraged.yml | 1 + features/date-get-year-set-year.yml | 1 + features/mutation-events.yml | 3 +++ 8 files changed, 10 insertions(+) diff --git a/features/accessor-methods.yml b/features/accessor-methods.yml index 239ae0eff1a..3bf3a587890 100644 --- a/features/accessor-methods.yml +++ b/features/accessor-methods.yml @@ -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." 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: diff --git a/features/arguments-callee.yml b/features/arguments-callee.yml index 835e4e4d3bb..a5e2b6b8cdc 100644 --- a/features/arguments-callee.yml +++ b/features/arguments-callee.yml @@ -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: diff --git a/features/clip.yml b/features/clip.yml index ee50c375776..73a072f4583 100644 --- a/features/clip.yml +++ b/features/clip.yml @@ -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: diff --git a/features/color-adjust.yml b/features/color-adjust.yml index fe473e5dccd..039ac8e4ef0 100644 --- a/features/color-adjust.yml +++ b/features/color-adjust.yml @@ -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: diff --git a/features/color-contrast.yml b/features/color-contrast.yml index f6a04a80c7d..482c87b5a0c 100644 --- a/features/color-contrast.yml +++ b/features/color-contrast.yml @@ -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 diff --git a/features/css-object-model-discouraged.yml b/features/css-object-model-discouraged.yml index e250df6303b..26e254b3877 100644 --- a/features/css-object-model-discouraged.yml +++ b/features/css-object-model-discouraged.yml @@ -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: diff --git a/features/date-get-year-set-year.yml b/features/date-get-year-set-year.yml index bfed0819dd1..11a94c9138b 100644 --- a/features/date-get-year-set-year.yml +++ b/features/date-get-year-set-year.yml @@ -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 diff --git a/features/mutation-events.yml b/features/mutation-events.yml index f8457161128..6ac9dbe3aa3 100644 --- a/features/mutation-events.yml +++ b/features/mutation-events.yml @@ -4,8 +4,11 @@ description: Mutation events like `DOMSubtreeModified`, `DOMNodeInserted`, or `D spec: https://w3c.github.io/uievents/ group: dom discouraged: + pending_removal: true + 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: From c312a788cdb2b048a4b8adc12f02759020f048a0 Mon Sep 17 00:00:00 2001 From: "Daniel D. Beck" Date: Thu, 14 Aug 2025 14:30:09 +0200 Subject: [PATCH 2/5] Add discouragement reason to SVG 1.1 --- features/svg-discouraged.yml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/features/svg-discouraged.yml b/features/svg-discouraged.yml index 34dd968bd42..9e6f817deb9 100644 --- a/features/svg-discouraged.yml +++ b/features/svg-discouraged.yml @@ -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 From 18f1c791634cf8de53c0e590546bee5762931f59 Mon Sep 17 00:00:00 2001 From: "Daniel D. Beck" Date: Thu, 4 Sep 2025 18:56:17 +0200 Subject: [PATCH 3/5] Add discouraged embellishments to the schema --- schemas/data.schema.json | 9 +++++++++ types.ts | 4 ++++ 2 files changed, 13 insertions(+) diff --git a/schemas/data.schema.json b/schemas/data.schema.json index 2d34661eed7..d577863f52f 100644 --- a/schemas/data.schema.json +++ b/schemas/data.schema.json @@ -74,9 +74,18 @@ "type": "string" }, "type": "array" + }, + "reason": { + "description": "A brief, developer-focused description of why the feature is discouraged", + "type": "string" + }, + "removal_expected_date": { + "description": "A predicted removal date, as in \"2029-12-31\". Only set if there's an announced plan by all currently-implementing vendors to unship the feature.", + "type": "string" } }, "required": [ + "reason", "according_to" ], "type": "object" diff --git a/types.ts b/types.ts index d1492262104..f4a71b0b812 100644 --- a/types.ts +++ b/types.ts @@ -72,6 +72,10 @@ interface SupportStatus extends Status { } interface Discouraged { + /** A brief, developer-focused description of why the feature is discouraged */ + reason: string; + /** A predicted removal date, as in "2029-12-31". Only set if there's an announced plan by all currently-implementing vendors to unship the feature. */ + removal_expected_date?: string; /** Links to a formal discouragement notice, such as specification text, intent-to-unship, etc. */ according_to: string[]; /** IDs for features that substitute some or all of this feature's utility */ From 4b53814d0100f00f96f54686ffe88e0049abe6d9 Mon Sep 17 00:00:00 2001 From: "Daniel D. Beck" Date: Thu, 11 Sep 2025 15:43:36 +0200 Subject: [PATCH 4/5] Convert `removal_expected_date` to `removal_date` for easier maintenance --- schemas/data.schema.json | 4 ++-- types.ts | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/schemas/data.schema.json b/schemas/data.schema.json index d577863f52f..1b7749def53 100644 --- a/schemas/data.schema.json +++ b/schemas/data.schema.json @@ -79,8 +79,8 @@ "description": "A brief, developer-focused description of why the feature is discouraged", "type": "string" }, - "removal_expected_date": { - "description": "A predicted removal date, as in \"2029-12-31\". Only set if there's an announced plan by all currently-implementing vendors to unship the feature.", + "removal_date": { + "description": "An expected or actual removal date, as in \"2029-12-31\". Only set if there's an announced plan by all currently-implementing vendors to unship the feature, or the feature has already been unshipped from all browsers.", "type": "string" } }, diff --git a/types.ts b/types.ts index f4a71b0b812..930ef00a609 100644 --- a/types.ts +++ b/types.ts @@ -74,8 +74,8 @@ interface SupportStatus extends Status { interface Discouraged { /** A brief, developer-focused description of why the feature is discouraged */ reason: string; - /** A predicted removal date, as in "2029-12-31". Only set if there's an announced plan by all currently-implementing vendors to unship the feature. */ - removal_expected_date?: string; + /** An expected or actual removal date, as in "2029-12-31". Only set if there's an announced plan by all currently-implementing vendors to unship the feature, or the feature has already been unshipped from all browsers. */ + removal_date?: string; /** Links to a formal discouragement notice, such as specification text, intent-to-unship, etc. */ according_to: string[]; /** IDs for features that substitute some or all of this feature's utility */ From 3acf7334a9becd8fcb291db62d390f34fcd4f2a9 Mon Sep 17 00:00:00 2001 From: "Daniel D. Beck" Date: Thu, 11 Sep 2025 15:44:03 +0200 Subject: [PATCH 5/5] Add more reasons --- features/date-to-gmt-string.yml | 2 ++ features/device-queries.yml | 1 + features/document-colors.yml | 1 + features/document-write.yml | 1 + features/escape-unescape.yml | 1 + features/execcommand.yml | 1 + features/external.yml | 1 + features/font-stretch.yml | 1 + features/functions-caller-arguments.yml | 1 + features/glyph-orientation-vertical.yml | 1 + features/host-context.yml | 5 ++--- features/html-wrapper-methods.yml | 1 + features/ime-mode.yml | 4 ++++ features/import-assertions.yml | 2 ++ features/is-input-pending.yml | 1 + features/mediacontroller.yml | 1 + features/mutation-events.yml | 2 +- features/overflow-overlay.yml | 2 ++ features/page-break-aliases.yml | 1 + features/performancetiming.yml | 1 + features/portal.yml | 2 +- features/private-network-access.yml | 2 ++ features/proto.yml | 1 + features/regexp-compile.yml | 1 + features/regexp-static-properties.yml | 4 ++++ features/speech-recognition-grammar.yml | 3 ++- features/table-discouraged.yml | 3 ++- features/text-decoration-line-blink.yml | 1 + features/webvr.yml | 1 + features/with.yml | 12 +----------- features/word-break-break-word.yml | 4 +++- features/writing-mode-svg-values.yml | 1 + 32 files changed, 47 insertions(+), 19 deletions(-) diff --git a/features/date-to-gmt-string.yml b/features/date-to-gmt-string.yml index 0a8f3fb00f7..4030d54c32b 100644 --- a/features/date-to-gmt-string.yml +++ b/features/date-to-gmt-string.yml @@ -2,8 +2,10 @@ name: toGMTString() description: The `toGMTString()` method of `Date` objects is an alias to the `toUTCString()` method. spec: https://tc39.es/ecma262/multipage/additional-ecmascript-features-for-web-browsers.html#sec-date.prototype.togmtstring discouraged: + reason: The method exists "principally for compatibility with old code." according_to: - https://tc39.es/ecma262/multipage/additional-ecmascript-features-for-web-browsers.html#sec-additional-ecmascript-features-for-web-browsers + - https://tc39.es/ecma262/multipage/additional-ecmascript-features-for-web-browsers.html#sec-date.prototype.togmtstring # No `alternatives` because it would be `alternatives: [date]`. In the future # it'd be nice to have an internal reference to the `toUTCString()` method # instead. diff --git a/features/device-queries.yml b/features/device-queries.yml index 393668f43a6..3061afe7762 100644 --- a/features/device-queries.yml +++ b/features/device-queries.yml @@ -3,6 +3,7 @@ description: The `device-aspect-ratio`, `device-height`, and `device-width` medi spec: https://drafts.csswg.org/mediaqueries-5/#mf-deprecated group: media-queries discouraged: + reason: Device media queries do not reflect available layout, only the physical size of the device. according_to: - https://drafts.csswg.org/mediaqueries-5/#mf-deprecated alternatives: diff --git a/features/document-colors.yml b/features/document-colors.yml index f4483dcebdd..93929826ebd 100644 --- a/features/document-colors.yml +++ b/features/document-colors.yml @@ -2,6 +2,7 @@ name: Document colors description: A document's `bgColor`, `fgColor`, `alinkColor`, `linkColor`, and `vlinkColor` properties get and set the background, foreground, active link, link, and visited link colors of that document. spec: https://html.spec.whatwg.org/multipage/obsolete.html discouraged: + reason: Document color attributes are superseded by CSS. according_to: - https://html.spec.whatwg.org/multipage/obsolete.html alternatives: diff --git a/features/document-write.yml b/features/document-write.yml index d4afcff6796..6d306ec6f0f 100644 --- a/features/document-write.yml +++ b/features/document-write.yml @@ -4,6 +4,7 @@ spec: https://html.spec.whatwg.org/multipage/dynamic-markup-insertion.html discouraged: # The spec doesn't actually discourage against open and close, but these methods are # really only useful for writing anyway, so we're marking the whole feature as discouraged. + reason: The dynamic markup insertion API, which includes `document.write()`, has "very idiosyncratic behavior" which can be difficult to debug. according_to: - https://html.spec.whatwg.org/multipage/dynamic-markup-insertion.html#document.write() alternatives: diff --git a/features/escape-unescape.yml b/features/escape-unescape.yml index a2c3ec3d197..9d0d64bb41a 100644 --- a/features/escape-unescape.yml +++ b/features/escape-unescape.yml @@ -3,6 +3,7 @@ description: The `escape()` and `unescape()` built-in Javascript methods encode spec: https://tc39.es/ecma262/multipage/additional-ecmascript-features-for-web-browsers.html#sec-escape-string group: javascript discouraged: + reason: TC39 included the `escape()` and `unescape()` 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." 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: [javascript]`. In the diff --git a/features/execcommand.yml b/features/execcommand.yml index f84249f44ae..991ef96db5d 100644 --- a/features/execcommand.yml +++ b/features/execcommand.yml @@ -3,6 +3,7 @@ description: The `execCommand()` method reads and writes from the clipboard and spec: https://w3c.github.io/editing/docs/execCommand/ group: clipboard discouraged: + reason: The `execCommand()` method is "not implemented consistently or fully by user agents, and it is not expected that this will change in the foreseeable future." according_to: - https://w3c.github.io/editing/docs/execCommand/ alternatives: diff --git a/features/external.yml b/features/external.yml index a31b05a4537..3dd6d57059e 100644 --- a/features/external.yml +++ b/features/external.yml @@ -2,6 +2,7 @@ name: window.external description: The `window.external.AddSearchProvider()` and `window.external.IsSearchProviderInstalled()` do nothing. Historically, they added external search providers to the browser. spec: https://html.spec.whatwg.org/multipage/obsolete.html#external discouraged: + reason: The `window.external.AddSearchProvider()` and `window.external.IsSearchProviderInstalled()` methods do nothing, by specification. according_to: - https://html.spec.whatwg.org/multipage/obsolete.html#external compat_features: diff --git a/features/font-stretch.yml b/features/font-stretch.yml index 88b63ec2a20..ead6fdcd870 100644 --- a/features/font-stretch.yml +++ b/features/font-stretch.yml @@ -2,6 +2,7 @@ name: font-stretch description: The `font-stretch` CSS property selects a font face from a font family based on width, either by a keyword such as `condensed` or a percentage. spec: https://drafts.csswg.org/css-fonts-4/#font-stretch-prop discouraged: + reason: The `font-stretch` CSS property is superseded by `font-width`. according_to: - https://drafts.csswg.org/css-fonts-4/#font-stretch-prop alternatives: diff --git a/features/functions-caller-arguments.yml b/features/functions-caller-arguments.yml index 7a2be05810e..fb9abf14836 100644 --- a/features/functions-caller-arguments.yml +++ b/features/functions-caller-arguments.yml @@ -3,6 +3,7 @@ description: The `caller` and `arguments` properties of a non-strict mode `Funct group: javascript spec: https://tc39.es/ecma262/multipage/error-handling-and-language-extensions.html#sec-forbidden-extensions discouraged: + reason: The `caller` and `arguments` properties of a `Function` object are not available in strict mode code. according_to: - https://tc39.es/ecma262/multipage/error-handling-and-language-extensions.html#sec-forbidden-extensions compat_features: diff --git a/features/glyph-orientation-vertical.yml b/features/glyph-orientation-vertical.yml index 560d3e35f57..4284c824445 100644 --- a/features/glyph-orientation-vertical.yml +++ b/features/glyph-orientation-vertical.yml @@ -3,6 +3,7 @@ description: The `glyph-orientation-vertical` CSS property sets the orientation spec: https://drafts.csswg.org/css-writing-modes-4/#glyph-orientation group: css discouraged: + reason: The `glyph-orientation-vertical` property was defined by SVG 1.1 and formally obsoleted by SVG 2. according_to: - https://drafts.csswg.org/css-writing-modes-4/#glyph-orientation alternatives: diff --git a/features/host-context.yml b/features/host-context.yml index 5e34ae3f8d0..cec2e3e5022 100644 --- a/features/host-context.yml +++ b/features/host-context.yml @@ -7,9 +7,8 @@ group: compat_features: - css.selectors.host-context discouraged: - # reason: > - # The CSS Working Group removed it from the specification, due to opposition - # from vendors, performance considerations, and interest in alternatives. + reason: > + The CSS Working Group removed `:host-context()` from the specification, due to opposition from vendors, performance considerations, and interest in alternatives. according_to: - https://github.com/w3c/csswg-drafts/issues/1914#issuecomment-2737310093 alternatives: diff --git a/features/html-wrapper-methods.yml b/features/html-wrapper-methods.yml index 45ac41987f9..00215afed92 100644 --- a/features/html-wrapper-methods.yml +++ b/features/html-wrapper-methods.yml @@ -3,6 +3,7 @@ description: JavaScript built-in methods such as, `String.bold()` and `String.it spec: https://tc39.es/ecma262/multipage/additional-ecmascript-features-for-web-browsers.html#sec-additional-properties-of-the-string.prototype-object group: javascript discouraged: + reason: HTML wrapper methods exist only for backwards compatibility. Use DOM APIs to create elements instead. according_to: - https://tc39.es/ecma262/multipage/additional-ecmascript-features-for-web-browsers.html#sec-additional-ecmascript-features-for-web-browsers alternatives: diff --git a/features/ime-mode.yml b/features/ime-mode.yml index c0b8ac2f8c6..59c3f29febd 100644 --- a/features/ime-mode.yml +++ b/features/ime-mode.yml @@ -3,7 +3,11 @@ description: The `ime-mode` CSS property sets the state of the input method edit spec: https://drafts.csswg.org/css-ui-3/#input-method-editor group: css discouraged: + reason: You should not modify the state of input method editor. Instead, you should use hints (such as a `lang` or `inputmode` attribute) to help the browser select the right user interface for text input. according_to: - https://drafts.csswg.org/css-ui-3/#input-method-editor + alternatives: + - inputmode + - lang-attr compat_features: - css.properties.ime-mode diff --git a/features/import-assertions.yml b/features/import-assertions.yml index edffeb81c37..403d310d90d 100644 --- a/features/import-assertions.yml +++ b/features/import-assertions.yml @@ -2,6 +2,8 @@ name: Import assertions description: 'Module `import … assert { type: "json" }` and `import … assert { type: "css" }` JavaScript statements load JSON and CSS data.' spec: https://github.com/tc39/proposal-import-attributes/tree/abca60286360b47f9a6be25a28f489c2cb157beb discouraged: + reason: Import assertions are superseded by import attributes. + removal_date: 2024-06-13 according_to: - https://github.com/tc39/proposal-import-attributes/pull/131 alternatives: diff --git a/features/is-input-pending.yml b/features/is-input-pending.yml index c9fab717d85..f52144d3e1d 100644 --- a/features/is-input-pending.yml +++ b/features/is-input-pending.yml @@ -2,6 +2,7 @@ name: isInputPending() description: The `navigator.scheduling.isInputPending()` method checks if there are pending input events, such as touch or mouse events. This allows you to yield from long-running scripts that might be blocking user interaction. spec: https://wicg.github.io/is-input-pending/ discouraged: + reason: The `navigator.scheduling.isInputPending()` method may incorrectly return `false` and is not the only case where you might expect to yield. according_to: - https://web.dev/articles/optimize-long-tasks#isinputpending alternatives: diff --git a/features/mediacontroller.yml b/features/mediacontroller.yml index 5a0ea68e403..4102afef5d1 100644 --- a/features/mediacontroller.yml +++ b/features/mediacontroller.yml @@ -2,6 +2,7 @@ name: MediaController description: "The playback of multiple `