Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add a guideline for setting deprecated #15703

Merged
merged 6 commits into from
Apr 13, 2022
Merged

Add a guideline for setting deprecated #15703

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
5ae217b
Add a guideline for setting `deprecated`
ddbeck Jul 2, 2021
f8878c9
Add PR link
ddbeck Apr 7, 2022
4372ad0
Remove redundant text
ddbeck Apr 7, 2022
96925e4
s/formally/authoritatively
ddbeck Apr 7, 2022
e39ee13
Revise bullets to make each point more distinctive
ddbeck Apr 7, 2022
2e973fd
More active-ish voice
ddbeck Apr 7, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 18 additions & 0 deletions docs/data-guidelines.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -426,3 +426,21 @@ Note that APIs available on only _some_ types of workers are not considered glob
- The `requestAnimationFrame()` function, available in `Window` and `DedicatedWorkerGlobalScope`.

This guideline is based on a discussion in [#11518](https://github.com/mdn/browser-compat-data/pull/11518).

## Setting `deprecated`

Set `deprecated` to `true` to show that a feature has been authoritatively discouraged from use.

The `deprecated` status captures the many ways standards organizations (and, for non-standard features, vendors) mark features as disfavored. This includes features that are on the path to removal or features that are discouraged from use despite their retention for backwards compatibility.

Evidence for setting `deprecated` to `true` includes:

- _Obsolete_, _legacy_, _deprecated_, _end-of-life_, or similar terminology in a specification
- Removal of a feature from a specification
- Specification text that cautions developers against new use of the feature
- Formal discouragement statements from a relevant standards body (for example, meeting minutes that show a committee achieving consensus for removal from a specification, even if the removal has not yet taken place)
- For non-standard features, notice from implementing browsers (for example, a console deprecation warning) or vendor documentation

Do not set `deprecated` to `true` for features that are merely old or unpopular, no matter how many [_considered harmful_](https://en.wikipedia.org/wiki/Considered_harmful) blog posts they may have garnered. For example, although web developers may prefer `fetch` over `XMLHttpRequest`, `XMLHttpRequest` is not deprecated.

This guideline was proposed in [#15703](https://github.com/mdn/browser-compat-data/pull/15703). See [mdn/content#5549](https://github.com/mdn/content/discussions/5549) and [#10490](https://github.com/mdn/browser-compat-data/issues/10490) for further discussion on the use of "deprecated."