From 54386eed02c4db3cda9e443747e1fc8dcceff73d Mon Sep 17 00:00:00 2001 From: "Daniel D. Beck" Date: Mon, 19 Apr 2021 13:47:26 +0100 Subject: [PATCH 1/6] Revise definition of `experimental` status --- schemas/compat-data-schema.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/schemas/compat-data-schema.md b/schemas/compat-data-schema.md index 5cdf2e2a4ede6..fd6a1a2d845cb 100644 --- a/schemas/compat-data-schema.md +++ b/schemas/compat-data-schema.md @@ -447,10 +447,12 @@ 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. +- `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 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. From 9c5f1aaf64e5c7965d04c49d1221097b71f0434a Mon Sep 17 00:00:00 2001 From: "Daniel D. Beck" Date: Mon, 19 Apr 2021 13:50:34 +0100 Subject: [PATCH 2/6] Reformat all `status` field descriptions for symmetry --- schemas/compat-data-schema.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/schemas/compat-data-schema.md b/schemas/compat-data-schema.md index fd6a1a2d845cb..fa0aefbdcf6c9 100644 --- a/schemas/compat-data-schema.md +++ b/schemas/compat-data-schema.md @@ -453,10 +453,13 @@ an object named `status` and has three mandatory properties: If `experimental` is `false`, it means the functionality is mature and no significant 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. +- `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": { From 41d8eb3e2ace47568f875805f2494f8b97427feb Mon Sep 17 00:00:00 2001 From: "Daniel D. Beck" Date: Mon, 19 Apr 2021 14:39:57 +0100 Subject: [PATCH 3/6] Add guideline for setting experimental status --- docs/data-guidelines.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/docs/data-guidelines.md b/docs/data-guidelines.md index c7f76477b3d32..6006aa117c022 100644 --- a/docs/data-guidelines.md +++ b/docs/data-guidelines.md @@ -280,3 +280,23 @@ 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`. + +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`. + +If a feature has been supported by one and only one engine without major changes for two or more years (relative to the most-recent browser release introducing support for the feature, or the most-recent browser release since the last major change) , then `experimental` may be set to `false`. + +| 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 value supported in Safari, released last week. | Yes | +| 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 [#TK](). From 36dd033b40d5da7f9f0789b49a6743b297d5f50e Mon Sep 17 00:00:00 2001 From: "Daniel D. Beck" Date: Mon, 19 Apr 2021 15:00:06 +0100 Subject: [PATCH 4/6] Add pull number --- docs/data-guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/data-guidelines.md b/docs/data-guidelines.md index 6006aa117c022..5648fa899a941 100644 --- a/docs/data-guidelines.md +++ b/docs/data-guidelines.md @@ -299,4 +299,4 @@ If a feature has been supported by one and only one engine without major changes | A CSS value supported in Safari, released last week. | Yes | | 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 [#TK](). +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). From 4ab8d6664b9a58d39c14d59872ef70ebe295a2b8 Mon Sep 17 00:00:00 2001 From: "Daniel D. Beck" Date: Mon, 19 Apr 2021 17:34:03 +0100 Subject: [PATCH 5/6] =?UTF-8?q?Fix:=20CSS=20value=20=E2=86=92=20CSS=20prop?= =?UTF-8?q?erty=20value?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/data-guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/data-guidelines.md b/docs/data-guidelines.md index 5648fa899a941..0aa3ac5876ef6 100644 --- a/docs/data-guidelines.md +++ b/docs/data-guidelines.md @@ -296,7 +296,7 @@ If a feature has been supported by one and only one engine without major changes | 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 value supported in Safari, released last week. | Yes | +| A CSS property value supported in Safari, released last week. | Yes | | 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). From 05429dcb5a213c7c83db7658f2ddbd373126418f Mon Sep 17 00:00:00 2001 From: "Daniel D. Beck" Date: Wed, 21 Apr 2021 18:07:29 +0100 Subject: [PATCH 6/6] Revise experimental sunset conditions --- docs/data-guidelines.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/data-guidelines.md b/docs/data-guidelines.md index 0aa3ac5876ef6..9766fccdab1c7 100644 --- a/docs/data-guidelines.md +++ b/docs/data-guidelines.md @@ -289,7 +289,10 @@ If a feature is supported behind flags only, no matter how many engines, then se 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`. -If a feature has been supported by one and only one engine without major changes for two or more years (relative to the most-recent browser release introducing support for the feature, or the most-recent browser release since the last major change) , then `experimental` may be set to `false`. +A single-engine feature's `experimental` status may expire and switch to `false` when the following conditions are met: + +- 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 | | --------------------------------------------------------------------------- | ------------ |