Skip to content

Commit c312b98

Browse files
committed
Explicitly note discouraged as an alternative to redirecting
1 parent 429d972 commit c312b98

File tree

1 file changed

+4
-1
lines changed

1 file changed

+4
-1
lines changed

docs/guidelines.md

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -94,6 +94,9 @@ You can do this when:
9494

9595
* Data consumers report that the original feature ID is confusing or misleading.
9696

97+
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).
98+
Instead, use [`discouraged` data](#discouraged) with one or more `alternatives`.
99+
97100
To move the feature:
98101

99102
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:
414417
If possible, use the single most broadly applicable reference, such as specification text.
415418
If a feature is removed from a specification, link to an issue, pull request, or commit showing the removal.
416419

417-
- Set one or more (optional) `alternative` feature IDs that are whole or partial substitutes for the discouraged feature.
420+
- Set one or more (optional) `alternatives` feature IDs that are whole or partial substitutes for the discouraged feature.
418421
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.
419422
Guide developers to the most relevant features that would help them stop using the discouraged feature.

0 commit comments

Comments
 (0)