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

Adopt new definition and guideline for experimental status #9933

Merged
merged 6 commits into from
May 11, 2021
Merged

Adopt new definition and guideline for experimental status #9933

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
54386ee
Revise definition of `experimental` status
ddbeck Apr 19, 2021
9c5f1aa
Reformat all `status` field descriptions for symmetry
ddbeck Apr 19, 2021
41d8eb3
Add guideline for setting experimental status
ddbeck Apr 19, 2021
36dd033
Add pull number
ddbeck Apr 19, 2021
4ab8d66
Fix: CSS value → CSS property value
ddbeck Apr 19, 2021
05429dc
Revise experimental sunset conditions
ddbeck Apr 21, 2021
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
23 changes: 23 additions & 0 deletions docs/data-guidelines.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -280,3 +280,26 @@ Members of this mixin are available to `HTMLAnchorElement` and `HTMLAreaElement`
```

This guideline was proposed in [#8929](https://github.com/mdn/browser-compat-data/issues/8929), based in part on previous discussion in [#472](https://github.com/mdn/browser-compat-data/issues/472).

## Choosing an experimental status

Generally, when a feature is supported by one and only one browser engine, set `experimental` to `true`. When a feature is supported by two or more engines, then set `experimental` to `false`. Some exceptions apply, however, for long-standing features and features behind flags and prefixes.

If a feature is supported behind flags only, no matter how many engines, then set `experimental` to `true`.
Elchi3 marked this conversation as resolved.
Show resolved Hide resolved

If a feature is supported behind incompatible prefixes only (such as `-webkit-` in one engine and `-moz-` in another), no matter how many engines support the feature overall, then set `experimental` to `true`. If two or more engines support a feature behind a common prefix (such as `-webkit-` only), then set `experimental` to `false`.
Elchi3 marked this conversation as resolved.
Show resolved Hide resolved

A single-engine feature's `experimental` status may expire and switch to `false` when the following conditions are met:
Elchi3 marked this conversation as resolved.
Show resolved Hide resolved

- The feature has been supported by default and without major changes by some browser for two or more years.
- If any other browser engine supports the feature behind a flag, then the behaviors are mutually compatible.

| Example | Experimental |
| --------------------------------------------------------------------------- | ------------ |
| An API supported in Chrome and Firefox, without flags or prefixes. | No |
| A CSS property supported in Chrome and Firefox, with the `-webkit-` prefix. | No |
| An HTTP header supported in Chrome and Firefox, behind flags. | Yes |
| A CSS property value supported in Safari, released last week. | Yes |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What if the feature is in a W3C recommendation and it just happens that Safari reached the finish line first?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If Safari crosses the finish line first, then it's still experimental until at least one engine catches up.

Part of the goal here is to clearly distinguish between experimental and standard track. Under this revised approach, experimental can be set independently of the standard track value (that is to say, the two values don't depend on each other—you don't even have to know what the standards status is to set the experimental status). This makes it more clear what experimental actually adds to our data set (a marker of consensus, or failing that, stasis) and lets us deal with features that are unchanging, but not standardized.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I get all that. It just seems misapplied here. If a feature is a full W3C recommendation, it's not a matter of if the second browser will implement. It's a matter of when. Knowing that fact is useful to developers. This information can help developers make other vendors aware that they should prioritize something. Here's how this would play out for Chrome.

  1. Safari implements a full recommendation.
  2. Developers see that Chrome hasn't implemented it yet, but they want it.
  3. They do one of three things: star an existing ticket on crbug.com, open a ticket on crbug.com, or they star the feature's entry on chromestatus.com.
  4. Chrome management sees a surge in developer interest and decides to prioritize it over The Obscure API. (Developer interest isn't the only thing we consider, but we do prioritize developer interest if we see a lot of it.)

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It just seems misapplied here.

First, a question: do you mean that the guideline and definition as written shouldn't result in this outcome? Or that you'd like to see different text that leads to a different outcome?

Second, what I want from this PR is to encourage the scenario you describe. Ideally, the experimental flag should be a signal to web developers to tell browser vendors and spec authors what they think of an emerging feature, including saying "I want this feature." I want to upstream the new experimental definition to MDN itself too, so this signal is stronger.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You overall heuristic seems misapplied to the case of a completely speced feature with one implementation, where 'speced feature' means one in a full recommendation.

what I want from this PR is to encourage the scenario you describe

The scenarios for a speced and unspeced feature are different.

  • For features in candidate recommendations, or wicg specs, or whatever, the signal vendors need is should the experimentation continue?
  • For features that are full recommendations, the signal vendors need is should we prioritize implementing feature X over feature Y? We have to do both because we agreed they should be part of the platform. Which do we want to do first?

Web developers would treat these differently as well.

  • For truly experimental features, I may not want to use the feature yet, or my employer may not let me use the feature in production. My shop doesn't let me use an open source polyfill. (Yes, that's a thing. I worked in one. There were liability concerns.) My shop's approved framework says they'll support it with a polyfill, but it's not coming for six months. Perhaps I'm overly cautious because I previously embraced an experimental feature and it got dropped. (Remember WebVR?)
  • For full recommendations, the most important concern with using is when will the other vendors catch up and will my framework support it in the meantime.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@jpmedley I'm not really following here. How good a spec here is actually very hard to judge, and browser implementers will not trust the status the spec claims for itself, whether that's "Unofficial Draft", "Living Standard", or "Recommendation".

I don't think we should use the spec's own claim about how stable it is as input to the "experimental" setting here, but base it entirely on implementation status, like @ddbeck is suggesting in this guideline.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't follow Joe either. I think this guideline is a lot clearer and I agree with @foolip and @ddbeck that it is good that we don't need to make any assumptions about the status of specs. @jpmedley feel free to start a discussion in an issue if you feel strongly about it.

Let's merge this. There is a lot of useful guideline work in here.

| An API supported in Firefox, released three years ago. | No |

This guideline was proposed in [#6905](https://github.com/mdn/browser-compat-data/issues/6905) and adopted in [#9933](https://github.com/mdn/browser-compat-data/pull/9933).
21 changes: 13 additions & 8 deletions schemas/compat-data-schema.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -447,14 +447,19 @@ A `matches` object contains hints to help automatically detect whether source co
The mandatory status property contains information about stability of the feature. It is
an object named `status` and has three mandatory properties:

- `experimental`: a `boolean` value that indicates this functionality is
intended to be an addition to the Web platform. Some features are added to
conduct tests. Set to `false`, it means the functionality is mature, and no
significant incompatible changes are expected in the future.
- `standard_track`: a `boolean` value indicating if the feature is part of an
active specification or specification process.
- `deprecated`: a `boolean` value that indicates if the feature is no longer recommended.
It might be removed in the future or might only be kept for compatibility purposes. Avoid using this functionality.
- `experimental`: a `boolean` value.

If `experimental` is `true`, it means that Web developers should experiment with this feature and provide feedback to browser vendors and standards authors about this feature. It also means that Web developers _should not_ rely on the feature's continued existence in its current (or potentially any) form in future browser releases.

If `experimental` is `false`, it means the functionality is mature and no significant changes are expected in the future.

- `standard_track`: a `boolean` value.

If `standard_track` is `true`, then the feature is part of an active specification or specification process.

- `deprecated`: a `boolean` value.

If `deprecated` is `true`, then the feature is no longer recommended. It might be removed in the future or might only be kept for compatibility purposes. Avoid using this functionality.

```json
"__compat": {
Expand Down