Add Baseline regression notes

docs/guidelines.md

@@ -423,3 +423,21 @@ When you set a `discouraged` block in a feature file, do:
 - Set one or more (optional) `alternatives` feature IDs that are whole or partial substitutes for the discouraged feature.
   An alternative doesn't have to be a narrow drop-in replacement for the discouraged feature but it must handle some use case of the discouraged feature.
   Guide developers to the most relevant features that would help them stop using the discouraged feature.
+
+## Notes
+
+Features may have notes.
+Presently, there is one type of note, a Baseline regression note.
+
+### Baseline regression note
+
+Use a note with a `category: baseline-regression` whenever the Baseline status goes backwards (such as from `"high"` to `"low"`).
+This note type applies to any regression, whether it was caused by changes in upstream data or an editorial override.
+
+In the `message` field, explain the cause of the regression.
+Write the message to developers, to help them understand whether the regression applies to their use case.
+If the cause is a newly-discovered or reported bug then briefly describe the nature of the bug.
+If the cause is a correction then briefly describe the nature and origin of the correction (usually, upstream data).
+
+In the `citations` field, include the URLs that are most important to understanding the nature and origin of the change.
+For example, if BCD marked a feature as a `partial_implementation` due to a browser bug, include the URL for the browser bug and the BCD pull request or issue where the `partial_implementation` status was agreed.

features/content-visibility.yml

@@ -3,12 +3,15 @@ description: The `content-visibility` CSS property delays rendering an element,
 spec: https://drafts.csswg.org/css-contain-2/#content-visibility
 group: css
 caniuse: css-content-visibility
-# TODO: https://github.com/web-platform-dx/web-features/issues/1971
-# Status changed: https://github.com/web-platform-dx/web-features/pull/2591
-# 2025-01-30 — low → false — Safari hides text behind `content-visibility: auto` from "Find…" in the page.
-# References:
-# - https://github.com/mdn/browser-compat-data/pull/25781
-# - https://bugs.webkit.org/show_bug.cgi?id=283846
+notes:
+  - category: baseline-regression
+    date: 2025-01-30
+    old_baseline_value: low
+    new_baseline_value: false
+    message: >
+      Safari prevents text in `content-visibility: auto` elements from being found with browser's "Find…" user interface.
+    citations:
+      - https://bugs.webkit.org/show_bug.cgi?id=283846
 compat_features:
   - api.ContentVisibilityAutoStateChangeEvent
   - api.ContentVisibilityAutoStateChangeEvent.ContentVisibilityAutoStateChangeEvent

features/createimagebitmap.yml

@@ -2,6 +2,15 @@ name: createImageBitmap
 description: The `createImageBitmap()` global method creates an `ImageBitmap` object from a source such as an image, SVG, blob, or canvas. An `ImageBitmap` object represents pixel data that can be drawn to a canvas with lower latency than other types, such as `ImageData`.
 spec: https://html.spec.whatwg.org/multipage/imagebitmap-and-animations.html#imagebitmap
 caniuse: createimagebitmap
+notes:
+  - date: 2025-08-11
+    category: baseline-regression
+    old_baseline_value: high
+    new_baseline_value: low
+    message: >
+      This feature's status was recalculated to be more consistent with caniuse's criteria for full support, requiring `SVGImageElement` as a supported image source.
+    citations:
+      - https://github.com/web-platform-dx/web-features/pull/3173
 status:
   compute_from:
     - api.createImageBitmap

features/font-variant-position.yml

@@ -2,9 +2,13 @@ name: font-variant-position
 description: The `font-variant-position` CSS property sets whether to use alternate glyphs for subscript and superscript text.
 spec: https://drafts.csswg.org/css-fonts-4/#font-variant-position-prop
 group: font-features
-# TODO: https://github.com/web-platform-dx/web-features/issues/1971
-# Status changed: https://github.com/web-platform-dx/web-features/pull/1958
-# 2024-10-15 — low → false — Chrome, Edge, and Safari do not implement font synthesis for missing superscript or subscript glyphs.
-# References:
-# - https://issues.chromium.org/issues/352218916
-# - https://bugs.webkit.org/show_bug.cgi?id=151471
+notes:
+  - date: 2024-10-15
+    category: baseline-regression
+    old_baseline_value: low
+    new_baseline_value: false
+    message: >
+      Chrome, Edge, and Safari do not implement font synthesis for missing superscript or subscript glyphs.
+    citations:
+      - https://issues.chromium.org/issues/352218916
+      - https://bugs.webkit.org/show_bug.cgi?id=151471

features/link-rel-dns-prefetch.yml

@@ -2,11 +2,14 @@ name: '<link rel="dns-prefetch">'
 description: The `rel="dns-prefetch"` attribute for the `<link>` HTML element is a hint to the browser that the page or user is likely to request resources from another domain, so the browser should preemptively resolve DNS for the `href` value's domain.
 spec: https://html.spec.whatwg.org/multipage/links.html#link-type-dns-prefetch
 caniuse: link-rel-dns-prefetch
+notes:
+  - date: 2025-06-23
+    category: baseline-regression
+    old_baseline_value: low
+    new_baseline_value: false
+    message: >
+      Safari on iOS does not support this feature. Upstream data corrected an earlier report that it did.
+    citations:
+      - https://github.com/mdn/browser-compat-data/pull/27057
 compat_features:
   - html.elements.link.rel.dns-prefetch
-# TODO: https://github.com/web-platform-dx/web-features/issues/1971
-# Status changed: https://github.com/web-platform-dx/web-features/pull/3074/
-# 2025-06-23 — low → false — On iOS, it was erroneously reported that this feature was supported.
-# References:
-# - https://developer.apple.com/documentation/safari-release-notes/safari-26-release-notes#Networking
-# - https://github.com/mdn/browser-compat-data/pull/27057

features/popover.yml

@@ -2,12 +2,16 @@ name: Popover
 description: The `popover` HTML attribute creates an overlay to display content on top of other page content. Popovers can be shown declaratively using HTML, or using the `showPopover()` method.
 spec: https://html.spec.whatwg.org/multipage/popover.html
 group: html
-# TODO: https://github.com/web-platform-dx/web-features/issues/1971
-# Status changed: https://github.com/web-platform-dx/web-features/pull/1797
-# 2024-09-18 — low → false — Safari on iOS has a bug that prevents dismissing popovers by touch.
-# References:
-# - https://github.com/mdn/browser-compat-data/issues/22927
-# - https://bugs.webkit.org/show_bug.cgi?id=267688
+# notes:
+#   - date: 2024-09-18
+#     category: baseline-regression
+#     old_baseline_value: low
+#     new_baseline_value: false
+#     message: >
+#       Safari on iOS has a bug that prevents light dismiss (tapping outside the element to close it).
+#     citations:
+#       - https://bugs.webkit.org/show_bug.cgi?id=267688
+#       - https://github.com/mdn/browser-compat-data/issues/22927
 status:
   compute_from:
     - api.HTMLElement.popover

features/streams.yml

@@ -2,12 +2,6 @@ name: Streams
 description: The streams API creates, composes, and consumes continuously generated data.
 spec: https://streams.spec.whatwg.org/
 group: streams
-# TODO: https://github.com/web-platform-dx/web-features/issues/1971
-# Status changed: https://github.com/web-platform-dx/web-features/pull/2358, https://github.com/web-platform-dx/web-features/pull/2491
-# 2024-12-19 — low → false — Regressed status to match Caniuse, which considers support beginning at BYOB shipping.
-# 2025-01-30 — false → high — Split BYOB into a separate "readable-byte-streams" feature. Linked that one to Caniuse.
-# References:
-# - https://caniuse.com/streams
 status:
   compute_from:
     - api.ReadableStream

index.ts

@@ -4,13 +4,13 @@ import path from 'path';
 import { Temporal } from '@js-temporal/polyfill';
 import { fdir } from 'fdir';
 import YAML from 'yaml';
-import { convertMarkdown } from "./text";
-import { GroupData, SnapshotData, WebFeaturesData } from './types';
 
-import { BASELINE_LOW_TO_HIGH_DURATION, coreBrowserSet, parseRangedDateString, getStatus } from 'compute-baseline';
+import { BASELINE_LOW_TO_HIGH_DURATION, coreBrowserSet, getStatus, parseRangedDateString } from 'compute-baseline';
 import { Compat } from 'compute-baseline/browser-compat-data';
 import { assertValidFeatureReference } from './assertions';
+import { convertMarkdown } from "./text";
 import { isMoved, isSplit } from './type-guards';
+import { FeatureData, GroupData, SnapshotData, WebFeaturesData } from './types';
 
 // The longest name allowed, to allow for compact display.
 const nameMaxLength = 80;
@@ -165,6 +165,13 @@ for (const [key, data] of yamlEntries('features')) {
         data.description = text;
         data.description_html = html;
     }
+    if (Array.isArray(data.notes)) {
+        for (const note of data.notes as FeatureData["notes"]) {
+            const { text, html } = convertMarkdown(data.description);
+            note.message = text;
+            note.message_html = html;
+        }
+    }
 
     // Compute Baseline high date from low date.
     if (data.status?.baseline === 'high') {
@@ -194,6 +201,15 @@ for (const [key, data] of yamlEntries('features')) {
         }
     }
 
+    // Ensure regression notes are still relevant
+    if (Array.isArray(data.notes)) {
+        for (const [index, note] of (data.notes as FeatureData["notes"]).entries()) {
+            if (note.new_baseline_value !== data.status.baseline) {
+                throw new Error(`regression note ${index} on ${key}.yml no longer applies (status is ${data.status.baseline}, note is ${note.new_baseline_value}). Delete this note.`);
+            }
+        }
+    }
+
     if (data.compat_features) {
         // Sort compat_features so that grouping and ordering in dist files has
         // no effect on what web-features users see.

schemas/data.schema.json

@@ -136,6 +136,60 @@
           "description": "Group identifiers",
           "$ref": "#/definitions/Strings"
         },
+        "notes": {
+          "description": "Notes about this feature",
+          "items": {
+            "additionalProperties": false,
+            "description": "A note describing a Baseline status regression. For example, a feature that has moved from Baseline low to not Baseline.",
+            "properties": {
+              "category": {
+                "const": "baseline-regression",
+                "description": "The topic of this note. This field is also a discriminator for any future note types",
+                "type": "string"
+              },
+              "citations": {
+                "description": "One or more URLs, such as bugs, used to justify the regression",
+                "items": {
+                  "type": "string"
+                },
+                "type": "array"
+              },
+              "date": {
+                "description": "The date that the regression was added to web-features data",
+                "type": "string"
+              },
+              "message": {
+                "description": "A short description of the cause of the regression as a plain text",
+                "type": "string"
+              },
+              "message_html": {
+                "description": "A short description of the cause of the regression as HTML",
+                "type": "string"
+              },
+              "new_baseline_value": {
+                "description": "The `baseline` status value after the regression",
+                "enum": ["low", false],
+                "type": ["string", "boolean"]
+              },
+              "old_baseline_value": {
+                "description": "The `baseline` status value before the regression",
+                "enum": ["high", "low"],
+                "type": "string"
+              }
+            },
+            "required": [
+              "category",
+              "date",
+              "message",
+              "message_html",
+              "citations",
+              "old_baseline_value",
+              "new_baseline_value"
+            ],
+            "type": "object"
+          },
+          "type": "array"
+        },
         "snapshot": {
           "description": "Snapshot identifiers",
           "$ref": "#/definitions/Strings"

types.quicktype.ts

@@ -95,6 +95,10 @@ export interface FeatureData {
    * Short name
    */
   name?: string;
+  /**
+   * Notes about this feature
+   */
+  notes?: Note[];
   /**
    * Snapshot identifiers
    */
@@ -135,6 +139,46 @@ export interface Discouraged {
 
 export type Kind = "feature" | "moved" | "split";
 
+/**
+ * A note describing a Baseline status regression. For example, a feature that has moved
+ * from Baseline low to not Baseline.
+ */
+export interface Note {
+  /**
+   * The topic of this note. This field is also a discriminator for any future note types
+   */
+  category: "baseline-regression";
+  /**
+   * One or more URLs, such as bugs, used to justify the regression
+   */
+  citations: string[];
+  /**
+   * The date that the regression was added to web-features data
+   */
+  date: string;
+  /**
+   * A short description of the cause of the regression as a plain text
+   */
+  message: string;
+  /**
+   * A short description of the cause of the regression as HTML
+   */
+  message_html: string;
+  /**
+   * The `baseline` status value after the regression
+   */
+  new_baseline_value: boolean | "low";
+  /**
+   * The `baseline` status value before the regression
+   */
+  old_baseline_value: OldBaselineValue;
+}
+
+/**
+ * The `baseline` status value before the regression
+ */
+export type OldBaselineValue = "high" | "low";
+
 /**
  * Whether a feature is considered a "Baseline" web platform feature and when it achieved
  * that status
@@ -143,7 +187,7 @@ export interface StatusHeadline {
   /**
    * Whether the feature is Baseline (low substatus), Baseline (high substatus), or not (false)
    */
-  baseline: boolean | BaselineEnum;
+  baseline: boolean | OldBaselineValue;
   /**
    * Date the feature achieved Baseline high status
    */
@@ -162,13 +206,11 @@ export interface StatusHeadline {
   support: Support;
 }
 
-export type BaselineEnum = "high" | "low";
-
 export interface Status {
   /**
    * Whether the feature is Baseline (low substatus), Baseline (high substatus), or not (false)
    */
-  baseline: boolean | BaselineEnum;
+  baseline: boolean | OldBaselineValue;
   /**
    * Date the feature achieved Baseline high status
    */

types.ts

@@ -5,7 +5,7 @@
 // nicer to work with in TypeScript.
 
 import type {
-  BaselineEnum as BaselineHighLow,
+  OldBaselineValue as BaselineHighLow,
   BrowserData,
   Browsers,
   Discouraged,
@@ -81,7 +81,12 @@ export type FeatureData = { kind: "feature" } & Required<
   Partial<
     Pick<
       QuicktypeMonolithicFeatureData,
-      "caniuse" | "compat_features" | "discouraged" | "group" | "snapshot"
+      | "caniuse"
+      | "compat_features"
+      | "discouraged"
+      | "group"
+      | "snapshot"
+      | "notes"
     >
   >;