From dde73f837823aa0c48453ef7219c8d0325e24c1f Mon Sep 17 00:00:00 2001 From: "Daniel D. Beck" Date: Tue, 13 May 2025 10:59:41 +0200 Subject: [PATCH 01/11] Add general `partial_implementation` guideline --- docs/data-guidelines/index.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/docs/data-guidelines/index.md b/docs/data-guidelines/index.md index 724972f955d756..3f16d227dfb3b0 100644 --- a/docs/data-guidelines/index.md +++ b/docs/data-guidelines/index.md @@ -52,6 +52,30 @@ Do not use `"preview"` for planned but not yet implemented support changes. In o This guideline was adopted to protect the quality of stable data in the face of schedule uncertainty. To learn more about the adoption of `"preview"` values, see [#12344](https://github.com/mdn/browser-compat-data/issues/12344) and [#10334](https://github.com/mdn/browser-compat-data/pull/10334). +## `"partial_implementation"` general usage guidelines + +You must set `"partial_implementation": true` when all of the following conditions are met: + +- The browser's support does not implement mandatory specified behavior. +- The browser's support is inconsistent with at least one other browser. +- The browser's support misleads or evades feature detection. + +Here are some example situations: + +- `"partial_implementation": false`: All implementing browsers ignore part of a feature's specified behavior in the same way. + This behavior is consistent and is a _de facto_ complete implementation. + +- `"partial_implementation": false`: All implementing browsers provide a form control user interface, but the specification gives the implementer discretion over its look and feel. + A developer complains that one browser's user interface lacks some desired quality that other browsers implement; they want it to be marked as partially implemented. + Use a note or non-standard behavioral subfeature instead. + +- `"partial_implementation": true`: `CSS.supports()` returns `true` for a property name and value, but the value has no behavior. + See [Non-functional defined names imply `"partial_implementation"`](#non-functional-defined-names-imply-partial_implementation). + +- `"partial_implementation": true`: One browser implements `ExampleInterface` but exposes it on the `Node` interface instead of the specified `Element` interface. + Other implementers use the correct parent interface. + This misleads feature detection (`"ExampleInterface" in Element.prototype` → false), so it's partially implemented. + ## `"partial_implementation"` requires a note If you set `"partial_implementation": true`, then write a note describing how the implementation is incomplete. From 78af72a98ef1b7eeb4c1f12944afff625cb86c94 Mon Sep 17 00:00:00 2001 From: "Daniel D. Beck" Date: Wed, 14 May 2025 17:14:48 +0200 Subject: [PATCH 02/11] Apply suggestions from code review Co-authored-by: Claas Augner <495429+caugner@users.noreply.github.com> --- docs/data-guidelines/index.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/data-guidelines/index.md b/docs/data-guidelines/index.md index 3f16d227dfb3b0..de889cbdd0e40b 100644 --- a/docs/data-guidelines/index.md +++ b/docs/data-guidelines/index.md @@ -68,6 +68,7 @@ Here are some example situations: - `"partial_implementation": false`: All implementing browsers provide a form control user interface, but the specification gives the implementer discretion over its look and feel. A developer complains that one browser's user interface lacks some desired quality that other browsers implement; they want it to be marked as partially implemented. Use a note or non-standard behavioral subfeature instead. + - `"partial_implementation": true`: `CSS.supports()` returns `true` for a property name and value, but the value has no behavior. See [Non-functional defined names imply `"partial_implementation"`](#non-functional-defined-names-imply-partial_implementation). From 781a82e55fe736a171ebf50f85e84f87c1380229 Mon Sep 17 00:00:00 2001 From: "Daniel D. Beck" Date: Thu, 15 May 2025 12:32:59 +0200 Subject: [PATCH 03/11] Improve example for confusing feature detection --- docs/data-guidelines/index.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/data-guidelines/index.md b/docs/data-guidelines/index.md index de889cbdd0e40b..1de415a88ca08d 100644 --- a/docs/data-guidelines/index.md +++ b/docs/data-guidelines/index.md @@ -73,9 +73,7 @@ Here are some example situations: - `"partial_implementation": true`: `CSS.supports()` returns `true` for a property name and value, but the value has no behavior. See [Non-functional defined names imply `"partial_implementation"`](#non-functional-defined-names-imply-partial_implementation). -- `"partial_implementation": true`: One browser implements `ExampleInterface` but exposes it on the `Node` interface instead of the specified `Element` interface. - Other implementers use the correct parent interface. - This misleads feature detection (`"ExampleInterface" in Element.prototype` → false), so it's partially implemented. +- `"partial_implementation": true`: One browser exposes a constructor, `Example()`, but it always throws an error. Other browsers implement the constructor's intended behavior. This confuses feature detection because `typeof Example === "function"` returns `true`, even though the constructor does not work. ## `"partial_implementation"` requires a note From 0c5887b5e97158c6acaa50bbdaa6f3da6d7a5788 Mon Sep 17 00:00:00 2001 From: "Daniel D. Beck" Date: Fri, 16 May 2025 10:10:53 +0200 Subject: [PATCH 04/11] Add text indicating that `partial_implementation` stands alone --- docs/data-guidelines/index.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/data-guidelines/index.md b/docs/data-guidelines/index.md index 1de415a88ca08d..5ba6c38a5edbb3 100644 --- a/docs/data-guidelines/index.md +++ b/docs/data-guidelines/index.md @@ -60,6 +60,10 @@ You must set `"partial_implementation": true` when all of the following conditio - The browser's support is inconsistent with at least one other browser. - The browser's support misleads or evades feature detection. +Setting `partial_implementation` stands alone. +Unlike `"version_added": false`, `partial_implementation` does not dictate support data to descendant features. +Likewise, a subfeature's `"version_added": false` does not imply `"version_added": false` or `"partial_implementation": true` for an ancestor feature. + Here are some example situations: - `"partial_implementation": false`: All implementing browsers ignore part of a feature's specified behavior in the same way. From 39f1533fb1cbe08df6d82fb3b99c18f0edabd771 Mon Sep 17 00:00:00 2001 From: "Daniel D. Beck" Date: Fri, 16 May 2025 10:11:53 +0200 Subject: [PATCH 05/11] Refine misleading text --- docs/data-guidelines/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/data-guidelines/index.md b/docs/data-guidelines/index.md index 5ba6c38a5edbb3..4d12a19fe196db 100644 --- a/docs/data-guidelines/index.md +++ b/docs/data-guidelines/index.md @@ -58,7 +58,7 @@ You must set `"partial_implementation": true` when all of the following conditio - The browser's support does not implement mandatory specified behavior. - The browser's support is inconsistent with at least one other browser. -- The browser's support misleads or evades feature detection. +- The browser's support causes confusing feature detection results. Setting `partial_implementation` stands alone. Unlike `"version_added": false`, `partial_implementation` does not dictate support data to descendant features. From 96f6850096da73926017d63668ba5f2550b3ead0 Mon Sep 17 00:00:00 2001 From: "Daniel D. Beck" Date: Tue, 19 Aug 2025 11:57:18 +0200 Subject: [PATCH 06/11] Add requirement for real-world negative impact on developers --- docs/data-guidelines/index.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/docs/data-guidelines/index.md b/docs/data-guidelines/index.md index 4d12a19fe196db..a394f318d35803 100644 --- a/docs/data-guidelines/index.md +++ b/docs/data-guidelines/index.md @@ -54,11 +54,19 @@ This guideline was adopted to protect the quality of stable data in the face of ## `"partial_implementation"` general usage guidelines +**This guideline was added in August 2025. +Feedback on this guideline is welcome. +If you have questions or concerns about how to apply it, [file an issue](https://github.com/mdn/browser-compat-data/issues/new/choose).** + You must set `"partial_implementation": true` when all of the following conditions are met: - The browser's support does not implement mandatory specified behavior. - The browser's support is inconsistent with at least one other browser. - The browser's support causes confusing feature detection results. +- The browser's support has a demonstrable negative impact on web developers. + +This list only covers cases where `"partial_implementation": true` is required. +`"partial_implementation": true` may apply in unusual situations not covered by this guideline, such as significant changes in a single-implementation feature's behavior before standardization. Setting `partial_implementation` stands alone. Unlike `"version_added": false`, `partial_implementation` does not dictate support data to descendant features. @@ -74,8 +82,12 @@ Here are some example situations: Use a note or non-standard behavioral subfeature instead. +- `"partial_implementation": false`: An implementing browser fails a web platform test against a corner case. + No web developers have reported the bug and it's unlikely that there are real-world applications that would attempt to use the corner case. + Use a note instead. + - `"partial_implementation": true`: `CSS.supports()` returns `true` for a property name and value, but the value has no behavior. - See [Non-functional defined names imply `"partial_implementation"`](#non-functional-defined-names-imply-partial_implementation). + See also: [Non-functional defined names imply `"partial_implementation"`](#non-functional-defined-names-imply-partial_implementation). - `"partial_implementation": true`: One browser exposes a constructor, `Example()`, but it always throws an error. Other browsers implement the constructor's intended behavior. This confuses feature detection because `typeof Example === "function"` returns `true`, even though the constructor does not work. From 8f59b116fc9da2238fdd0c2587023d7cca20b7f7 Mon Sep 17 00:00:00 2001 From: "Daniel D. Beck" Date: Tue, 19 Aug 2025 12:02:45 +0200 Subject: [PATCH 07/11] Add guideline to index --- docs/index.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/index.md b/docs/index.md index f077b2ff4f760d..d3657fcb443b32 100644 --- a/docs/index.md +++ b/docs/index.md @@ -68,7 +68,10 @@ An alphabetical index of keywords linking to relevant sections in the docs. --- -- **Partial implementation** – [Data guidelines: "partial_implementation" requires a note](./data-guidelines/index.md#partial_implementation-requires-a-note) +- **Partial implementation** + - [Data guidelines: `"partial_implementation"` general usage guidelines](./data-guidelines/index.md#partial_implementation-general-usage-guidelines) + - [Data guidelines: "partial_implementation" requires a note](./data-guidelines/index.md#partial_implementation-requires-a-note) + - **Permissions API** – [Data guidelines for API features](./data-guidelines/api.md#permissions-api-permissions-permissionname_permission) - **Preview support** – [Data guidelines: Choosing "preview" values](./data-guidelines/index.md#choosing-preview-values) - **Promises** – [Data guidelines for API features](./data-guidelines/api.md#methods-returning-promises-returns_promise) From 9e7380b86f5ebf51a0cd29b24862443d63a2bf75 Mon Sep 17 00:00:00 2001 From: "Daniel D. Beck" Date: Tue, 26 Aug 2025 09:49:03 +0200 Subject: [PATCH 08/11] Format provisional guideline text as a note Co-authored-by: Claas Augner <495429+caugner@users.noreply.github.com> --- docs/data-guidelines/index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/data-guidelines/index.md b/docs/data-guidelines/index.md index a394f318d35803..94cc43bd5fcbd0 100644 --- a/docs/data-guidelines/index.md +++ b/docs/data-guidelines/index.md @@ -54,9 +54,9 @@ This guideline was adopted to protect the quality of stable data in the face of ## `"partial_implementation"` general usage guidelines -**This guideline was added in August 2025. -Feedback on this guideline is welcome. -If you have questions or concerns about how to apply it, [file an issue](https://github.com/mdn/browser-compat-data/issues/new/choose).** +> ![NOTE] +> This guideline was added in August 2025, and feedback is welcome. +> If you have questions or concerns about how to apply it, [file an issue](https://github.com/mdn/browser-compat-data/issues/new/choose). You must set `"partial_implementation": true` when all of the following conditions are met: From 081f9243723bc505685cacb2a768441b09cb8436 Mon Sep 17 00:00:00 2001 From: "Daniel D. Beck" Date: Tue, 26 Aug 2025 09:49:39 +0200 Subject: [PATCH 09/11] Drop text about data cascading --- docs/data-guidelines/index.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/data-guidelines/index.md b/docs/data-guidelines/index.md index 94cc43bd5fcbd0..790f988abdfc72 100644 --- a/docs/data-guidelines/index.md +++ b/docs/data-guidelines/index.md @@ -68,9 +68,6 @@ You must set `"partial_implementation": true` when all of the following conditio This list only covers cases where `"partial_implementation": true` is required. `"partial_implementation": true` may apply in unusual situations not covered by this guideline, such as significant changes in a single-implementation feature's behavior before standardization. -Setting `partial_implementation` stands alone. -Unlike `"version_added": false`, `partial_implementation` does not dictate support data to descendant features. -Likewise, a subfeature's `"version_added": false` does not imply `"version_added": false` or `"partial_implementation": true` for an ancestor feature. Here are some example situations: From 3e10a3ac0b863f40189c6a1dfe4b2a29a7524ee7 Mon Sep 17 00:00:00 2001 From: "Daniel D. Beck" Date: Tue, 26 Aug 2025 09:48:32 +0200 Subject: [PATCH 10/11] Fix typos --- docs/data-guidelines/index.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/data-guidelines/index.md b/docs/data-guidelines/index.md index 790f988abdfc72..da6b38358b7f43 100644 --- a/docs/data-guidelines/index.md +++ b/docs/data-guidelines/index.md @@ -55,7 +55,7 @@ This guideline was adopted to protect the quality of stable data in the face of ## `"partial_implementation"` general usage guidelines > ![NOTE] -> This guideline was added in August 2025, and feedback is welcome. +> This guideline was added in August 2025 and feedback is welcome. > If you have questions or concerns about how to apply it, [file an issue](https://github.com/mdn/browser-compat-data/issues/new/choose). You must set `"partial_implementation": true` when all of the following conditions are met: @@ -68,7 +68,6 @@ You must set `"partial_implementation": true` when all of the following conditio This list only covers cases where `"partial_implementation": true` is required. `"partial_implementation": true` may apply in unusual situations not covered by this guideline, such as significant changes in a single-implementation feature's behavior before standardization. - Here are some example situations: - `"partial_implementation": false`: All implementing browsers ignore part of a feature's specified behavior in the same way. @@ -96,7 +95,7 @@ This guideline was proposed in [#7332](https://github.com/mdn/browser-compat-dat ## Non-functional defined names imply `"partial_implementation"` -If a browser recognizes an API name, but the API doesn’t have any discernable behavior, use `"partial_implementation": true` instead of `"version_added": false`, as if the feature has non-standard support, rather than no support. +If a browser recognizes an API name, but the API doesn’t have any discernible behavior, use `"partial_implementation": true` instead of `"version_added": false`, as if the feature has non-standard support, rather than no support. For example, suppose there is some specification for a Web API `NewFeature.method()`. Running `typeof NewFeature.method` in some browser returns `function` (not `undefined`), but the method, when called, returns `null` instead of an expected value. For that feature, set `"partial_implementation": true` and write a note describing the feature’s misbehavior. From 4b7d3c336fdb2e31f9583daa6960af9716d53c59 Mon Sep 17 00:00:00 2001 From: "Daniel D. Beck" Date: Tue, 26 Aug 2025 12:25:36 +0200 Subject: [PATCH 11/11] Add proposed and adopted text --- docs/data-guidelines/index.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/data-guidelines/index.md b/docs/data-guidelines/index.md index da6b38358b7f43..8ad4b0c27d8bbb 100644 --- a/docs/data-guidelines/index.md +++ b/docs/data-guidelines/index.md @@ -87,6 +87,8 @@ Here are some example situations: - `"partial_implementation": true`: One browser exposes a constructor, `Example()`, but it always throws an error. Other browsers implement the constructor's intended behavior. This confuses feature detection because `typeof Example === "function"` returns `true`, even though the constructor does not work. +This guideline was proposed and adopted in [#26780](https://github.com/mdn/browser-compat-data/pull/26780). + ## `"partial_implementation"` requires a note If you set `"partial_implementation": true`, then write a note describing how the implementation is incomplete.