From 49b448ef9195468c46d1d7f4912817aa74aa3b9d Mon Sep 17 00:00:00 2001 From: "Daniel D. Beck" Date: Thu, 24 Jul 2025 14:17:14 +0200 Subject: [PATCH 1/4] Add guidelines for moving and splitting features --- docs/guidelines.md | 62 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 62 insertions(+) diff --git a/docs/guidelines.md b/docs/guidelines.md index 181feb12705..854a8110652 100644 --- a/docs/guidelines.md +++ b/docs/guidelines.md @@ -77,6 +77,68 @@ The identifier should match the name, with these additional guidelines: - 👍 Recommended: `user-pseudos` - 👎 Not recommended: `user-valid-and-user-invalid` +### Move a feature to a new ID + +It’s possible to change or substitute a feature’s ID by creating a redirect from the original ID pointing to a new ID. +You can do this when: + +* The original feature ID is misspelled. +* The original feature ID breaks the identifier guidelines. +* Data consumers report that the original feature ID is confusing or misleading. +* The original feature should not have existed as an independent feature. + +To move the feature: + +1. If applicable, move the existing YAML files for the feature to the target ID filename. + For example, rename `features/numeric-seperators.yml` to `features/numeric-separators.yml`. + + If the original feature is being replaced by another feature, then move on to the next step. + +2. Create a new YAML file for the original target ID filename. + For example, create an empty file `features/numeric-seperators.yml`. + +3. Populate the following data in the new YAML file: + + ```yaml + kind: moved + redirect_target: TARGET-ID + ``` + + where `TARGET-ID` is the target ID. + +4. Regenerate the dist files. + Run `npm run dist`. + +5. Commit your work and open a pull request. + +### Split a feature into two or more other features + +Some features may need to be split in two or more parts. +You can do this when the original feature should not have existed as an independent feature in the first place. +For example, similarly-named compat keys that ought to have been additions to existing features were erroneously combined and assigned to a new feature. + +To split the feature: + +1. If the feature to be split has any keys listed in `compat_features`, then reassign the keys to the target features. + + To get the list of keys, you may need to first run `npm run undist -- $feature` where `$feature` is the path to the YAML file of the feature to be split. + +2. Replace the contents of the original feature YAML file with the following data: + + ```yaml + kind: split + redirect_targets: + - target-id1 + - target-id2 + ``` + + Replace the `target-id` values with two or more target ID strings. + +3. Regenerate the dist files. + Run `npm run dist`. + +4. Commit your work and open a pull request. + ## Descriptions The `description` field contains a short description of the feature in Markdown-formatted text, which is converted to HTML in the published package. From 89c60319381072b7ba7de1a88fc9d84f5fdbcaf7 Mon Sep 17 00:00:00 2001 From: "Daniel D. Beck" Date: Mon, 18 Aug 2025 14:06:21 +0200 Subject: [PATCH 2/4] Add examples for moving feature IDs --- docs/guidelines.md | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/docs/guidelines.md b/docs/guidelines.md index 854a8110652..87e16acca9f 100644 --- a/docs/guidelines.md +++ b/docs/guidelines.md @@ -82,10 +82,17 @@ The identifier should match the name, with these additional guidelines: It’s possible to change or substitute a feature’s ID by creating a redirect from the original ID pointing to a new ID. You can do this when: -* The original feature ID is misspelled. -* The original feature ID breaks the identifier guidelines. -* Data consumers report that the original feature ID is confusing or misleading. +* The original feature ID is misspelled. + For example, `numeric-seperators` (note spelling) data can be moved to `numeric-separators`. + +* The original feature ID breaks the identifier guidelines. + For example, `drones-initial-support` data can be moved to `drones`. + * The original feature should not have existed as an independent feature. + For example, `single-color-gradients` was a poorly-conceived feature, where [a specification change](https://github.com/w3c/csswg-drafts/issues/10092) simplified the specification, implementation, and tools, but produced no novel browser behavior that developers could use in an application. + Instead, all the compatibility keys for the feature were reassigned to `gradients`. + +* Data consumers report that the original feature ID is confusing or misleading. To move the feature: From c312b98ba951cedc31f54d7c3bdaa081c7b9f62c Mon Sep 17 00:00:00 2001 From: "Daniel D. Beck" Date: Wed, 3 Sep 2025 19:01:54 +0200 Subject: [PATCH 3/4] Explicitly note discouraged as an alternative to redirecting --- docs/guidelines.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/guidelines.md b/docs/guidelines.md index 87e16acca9f..badda527b1a 100644 --- a/docs/guidelines.md +++ b/docs/guidelines.md @@ -94,6 +94,9 @@ You can do this when: * Data consumers report that the original feature ID is confusing or misleading. +You must not do this when the feature has been superseded, such that the feature's name has changed and the exposed behaviors or API surface have changed (in shipping browsers, up to and including unshipping). +Instead, use [`discouraged` data](#discouraged) with one or more `alternatives`. + To move the feature: 1. If applicable, move the existing YAML files for the feature to the target ID filename. @@ -414,6 +417,6 @@ When you set a `discouraged` block in a feature file, do: If possible, use the single most broadly applicable reference, such as specification text. If a feature is removed from a specification, link to an issue, pull request, or commit showing the removal. -- Set one or more (optional) `alternative` feature IDs that are whole or partial substitutes for the discouraged feature. +- 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. From 9af061451d22bd854e5aa51e56dee7fcc01489d8 Mon Sep 17 00:00:00 2001 From: "Daniel D. Beck" Date: Mon, 15 Sep 2025 12:50:08 +0200 Subject: [PATCH 4/4] Provide directions on ordering `redirect_targets` https://github.com/web-platform-dx/web-features/pull/3181#discussion_r2344575538 --- docs/guidelines.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/guidelines.md b/docs/guidelines.md index badda527b1a..fae24d70be0 100644 --- a/docs/guidelines.md +++ b/docs/guidelines.md @@ -143,6 +143,9 @@ To split the feature: ``` Replace the `target-id` values with two or more target ID strings. + Order `redirect_targets` by the most widely-relevant features first. + For example, if the feature is split to separate a Baseline subset of a feature from a non-Baseline subset, then put the Baseline feature first. + If you must break a tie, use alphabetical order. 3. Regenerate the dist files. Run `npm run dist`.