Embellish discouraged data with more detail (#3193)

ddbeck · foolip · captainbrosset · web-flow · commit a3d848744b9c · 2025-12-01T17:53:17.000+01:00
Co-authored-by: Philip Jägenstedt &lt;philip@foolip.org&gt;
Co-authored-by: captainbrosset &lt;1152698+captainbrosset@users.noreply.github.com&gt;
Co-authored-by: LeoMcA &lt;755354+LeoMcA@users.noreply.github.com&gt;
Co-authored-by: Rumyra &lt;302715+Rumyra@users.noreply.github.com&gt;
diff --git a/assertions.ts b/assertions.ts
@@ -1,4 +1,5 @@
 import { isOrdinaryFeatureData } from "./type-guards";
+import { FeatureData } from "./types";
 import { WebFeaturesData } from "./types.quicktype";
 
 /**
@@ -26,4 +27,35 @@ export function assertValidFeatureReference(
   }
 }
 
+/**
+ * Assert that a discouraged feature with no supporting browsers has a
+ * `removal_date`.
+ *
+ * @export
+ * @param {string} id The ID of the feature to be checked
+ * @param {FeatureData} feature The ordinary feature data to be checked
+ */
+export function assertRequiredRemovalDateSet(
+  id: string,
+  feature: FeatureData,
+): void {
+  if (!feature.discouraged) {
+    return;
+  }
+  if (feature.discouraged.removal_date) {
+    return;
+  }
+  if (Object.keys(feature.status.support).length > 0) {
+    return;
+  }
+  if (
+    feature.compat_features &&
+    Object.keys(feature.status.by_compat_key).length > 0
+  )
+    return;
+  throw new Error(
+    `${id} is discouraged and has no reported support, so a removal date is required`,
+  );
+}
+
 // TODO: assertValidSnapshotReference
diff --git a/features/accessor-methods.yml b/features/accessor-methods.yml
@@ -3,6 +3,7 @@ description: The `__defineGetter__()` and `__defineSetter__()` methods of object
 spec: https://tc39.es/ecma262/multipage/fundamental-objects.html#sec-object.prototype-legacy-accessor-methods
 group: javascript
 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
@@ -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
@@ -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
@@ -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
@@ -3,9 +3,11 @@ 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
+  removal_date: 2022-10-19
   according_to:
     - https://github.com/w3c/csswg-drafts/issues/7557
     - https://github.com/w3c/csswg-drafts/commit/36594e9e8496a5ca83f1f1ee2b4a83bcdf28753b
diff --git 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
@@ -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/date-to-gmt-string.yml b/features/date-to-gmt-string.yml
@@ -3,8 +3,10 @@ description: The `toGMTString()` method of `Date` objects is an alias to the `to
 spec: https://tc39.es/ecma262/multipage/additional-ecmascript-features-for-web-browsers.html#sec-date.prototype.togmtstring
 group: javascript
 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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: JavaScript strict mode prohibits accessing the `caller` and `arguments` properties of a `Function` object.
   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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -2,6 +2,7 @@ name: MediaController
 description: "The playback of multiple `<video>` or `<audio>` elements can be coordinated by a `MediaController` instance, for example to synchronize a sign-language interpreter track with the main video track."
 spec: https://www.w3.org/TR/2018/SPSD-html5-20180327/embedded-content-0.html#synchronising-multiple-media-elements
 discouraged:
+  reason: The `MediaController` API was dropped from the specification due to lack of implementations.
   according_to:
     # The PR that removed the feature from the HTML spec was https://github.com/w3c/html/pull/357.
     # Linking to the issue discussion seems more appropriate.
diff --git 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:
+  removal_date: 2025-09-15
+  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:
diff --git a/features/overflow-overlay.yml b/features/overflow-overlay.yml
@@ -4,6 +4,8 @@ spec: https://drafts.csswg.org/css-overflow-3/#propdef-overflow
 group: css
 caniuse: css-overflow-overlay
 discouraged:
+  reason: >
+    Some old browsers may implement non-standard behavior for `overflow: overlay`.
   according_to:
     - https://drafts.csswg.org/css-overflow-3/#valdef-overflow-overlay
   alternatives:
diff --git a/features/page-break-aliases.yml b/features/page-break-aliases.yml
@@ -3,6 +3,7 @@ description: The `page-break-before`, `page-break-inside`, and `page-break-after
 spec: https://drafts.csswg.org/css-break-4/#page-break-properties
 group: layout
 discouraged:
+  reason: The `page-break-` alias properties exist only for backwards compatibility with pages that predate the `break-` properties.
   according_to:
     - https://drafts.csswg.org/css-break-4/#page-break-properties
   alternatives:
diff --git a/features/performancetiming.yml b/features/performancetiming.yml
@@ -3,6 +3,7 @@ description: The `window.performance.timing` and `window.performance.navigation`
 spec: https://w3c.github.io/navigation-timing/#obsolete
 group: performance
 discouraged:
+  reason: This feature is supserseded by the `PerformanceNavigationTiming` API.
   according_to:
     - https://w3c.github.io/navigation-timing/#obsolete
   alternatives:
diff --git a/features/portal.yml b/features/portal.yml
@@ -3,7 +3,8 @@ description: The `<portal>` HTML element embeds another page into the current pa
 spec: https://wicg.github.io/portals/
 caniuse: portals
 discouraged:
-  # "The Portals proposal is not currently being actively pursued."
+  reason: The `<portal>` element was removed from browsers in favor of other proposals.
+  removal_date: 2023-07-23
   according_to:
     - https://github.com/WICG/portals/blob/421e74f5bb3e12d6d439ad19654a1463a5cb9b0a/README.md?plain=1#L1
   alternatives:
diff --git a/features/private-network-access.yml b/features/private-network-access.yml
@@ -2,6 +2,8 @@ name: Private network access
 description: "The `Access-Control-Request-Private-Network: true` and `Access-Control-Allow-Private-Network: true` HTTP request and response headers establish permission for websites to make requests to internal networks, such as to routers."
 spec: https://wicg.github.io/private-network-access/
 discouraged:
+  removal_date: 2025-06-26
+  reason: Private network access caused compatibility problems and is superseded by local network access.
   according_to:
     - https://github.com/WICG/local-network-access?tab=readme-ov-file#local-network-access
     - https://developer.chrome.com/blog/pna-on-hold
diff --git a/features/proto.yml b/features/proto.yml
@@ -3,6 +3,7 @@ description: The `__proto__` property of objects partially exposes the prototype
 spec: https://tc39.es/ecma262/multipage/fundamental-objects.html#sec-object.prototype.__proto__
 group: javascript
 discouraged:
+  reason: Changing `__proto__` is slow and can cause surprising bugs.
   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: [object]`. In the
diff --git a/features/regexp-compile.yml b/features/regexp-compile.yml
@@ -3,6 +3,7 @@ description: The `compile()` method of `RegExp` objects recompiles an existing r
 spec: https://tc39.es/ecma262/multipage/additional-ecmascript-features-for-web-browsers.html#sec-regexp.prototype.compile
 group: regexps
 discouraged:
+  reason: The `compile()` method duplicates behavior of the `RegExp()` constructor and it exists only for backwards compatibility.
   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: [regexp]`. In the
diff --git a/features/regexp-static-properties.yml b/features/regexp-static-properties.yml
@@ -3,8 +3,12 @@ description: The `RegExp` object has several static properties to access the inp
 spec: https://github.com/tc39/proposal-regexp-legacy-features
 group: regexps
 discouraged:
+  reason: The `RegExp` static properties may have unintended side effects.
   according_to:
     - https://github.com/tc39/proposal-regexp-legacy-features
+  # No `alternatives` because it would be `alternatives: [regexp]`. In the
+  # future it'd be nice to have an internal reference to the RegExp instance
+  # methods. See: https://github.com/web-platform-dx/web-features/issues/2676
 compat_features:
   - javascript.builtins.RegExp.input
   - javascript.builtins.RegExp.lastMatch
diff --git a/features/speech-recognition-grammar.yml b/features/speech-recognition-grammar.yml
@@ -1,10 +1,11 @@
 name: Speech recognition grammar
-description: "The `SpeechRecognition.grammars` property of the Web Speech API represents a set of words or patterns of words that the recognition service should recognize, used for when the recognition service's accuracy is low. This feature has been removed due to advancements in speech recognition."
+description: "The `SpeechRecognition.grammars` property of the Web Speech API represents a set of words or patterns of words that the recognition service should recognize, used for when the recognition service's accuracy is low."
 spec: https://webaudio.github.io/web-speech-api/#speechreco-section
 discouraged:
   # SpeechGrammar and SpeechGrammarList have been removed from the Web Speech API spec.
   # There is no alternative API to point to because speech recognition has improved
   # significantly, removing the need for grammar-based recognition.
+  reason: Advancements in speech recognition mean that speech grammars are not needed to achieve low error rates.
   according_to:
     - https://github.com/WebAudio/web-speech-api/pull/117
 group: speech
diff --git 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
diff --git a/features/table-discouraged.yml b/features/table-discouraged.yml
diff --git a/features/target-within.yml b/features/target-within.yml
diff --git a/features/text-decoration-line-blink.yml b/features/text-decoration-line-blink.yml
diff --git a/features/webvr.yml b/features/webvr.yml
diff --git a/features/with.yml b/features/with.yml
diff --git a/features/word-break-break-word.yml b/features/word-break-break-word.yml
diff --git a/features/writing-mode-svg-values.yml b/features/writing-mode-svg-values.yml
diff --git a/index.ts b/index.ts
diff --git a/packages/web-features/README.md b/packages/web-features/README.md
diff --git a/schemas/data.schema.json b/schemas/data.schema.json
diff --git a/types.quicktype.ts b/types.quicktype.ts
diff --git a/types.ts b/types.ts
