Skip to content

Add general partial_implementation guideline #26780

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

Merged
caugner merged 13 commits into from
Aug 26, 2025
Merged

Add general partial_implementation guideline #26780

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
dde73f8
Add general `partial_implementation` guideline
ddbeck May 13, 2025
78af72a
Apply suggestions from code review
ddbeck May 14, 2025
781a82e
Improve example for confusing feature detection
ddbeck May 15, 2025
0c5887b
Add text indicating that `partial_implementation` stands alone
ddbeck May 16, 2025
39f1533
Refine misleading text
ddbeck May 16, 2025
fc9da77
Merge branch 'main' into general-partial-guideline
ddbeck Aug 19, 2025
96f6850
Add requirement for real-world negative impact on developers
ddbeck Aug 19, 2025
8f59b11
Add guideline to index
ddbeck Aug 19, 2025
9e7380b
Format provisional guideline text as a note
ddbeck Aug 26, 2025
081f924
Drop text about data cascading
ddbeck Aug 26, 2025
3e10a3a
Fix typos
ddbeck Aug 26, 2025
ce40a8b
Merge branch 'main' into general-partial-guideline
ddbeck Aug 26, 2025
4b7d3c3
Add proposed and adopted text
ddbeck Aug 26, 2025
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
39 changes: 38 additions & 1 deletion docs/data-guidelines/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,43 @@ 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

> ![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:

- The browser's support does not implement mandatory specified behavior.
- The browser's support is inconsistent with at least one other browser.
Copy link
Contributor

@captainbrosset captainbrosset May 22, 2025

Choose a reason for hiding this comment

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

What if it's the other browser that's wrong?

Copy link
Contributor

@caugner caugner May 22, 2025

Choose a reason for hiding this comment

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

I think what's meant here is:

At least one other browser implements this behavior.

Copy link
Contributor

@captainbrosset captainbrosset May 22, 2025

Choose a reason for hiding this comment

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

Ok. In that case, I'd suggest rephrasing.
Right now, this reads as "set partial implementation to true if this browser doesn't work like that other browser". And to me, I have no way of know which browser is right.

Copy link
Contributor

@hamishwillee hamishwillee May 22, 2025

Choose a reason for hiding this comment

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

@caugner (as you know and have commented) Given an interface, it is not uncommon for new properties or methods to be added later. At that point the parent interface becomes partial even if it was complete previously. My understanding though is that you wouldn't "go back" and capture that in the interface level. The interface would remain complete?

Copy link
Contributor

@chrisdavidmills chrisdavidmills May 23, 2025

Choose a reason for hiding this comment

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

My understanding of "complete" would be "complete at the time the data was written", so it would still hold true if another feature was added later. Does that need clarifying? It would be a real mess if people started going around retroactively marking data as partial because new features were added later.

Copy link
Contributor Author

@ddbeck ddbeck May 28, 2025

Choose a reason for hiding this comment

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

To answer some questions here:

Right now, this reads as "set partial implementation to true if this browser doesn't work like that other browser". And to me, I have no way of know which browser is right.

All three conditions must be met. The spec is almost always right—unless all implementers ignore the spec same exact way. It's possible to have partials for all implementers, if they all differ from the spec and they're not all mutually compatible.

At that point the parent interface becomes partial even if it was complete previously. My understanding though is that you wouldn't "go back" and capture that in the interface level. The interface would remain complete?

Partial data doesn't cascade to descendants and it doesn't bubble up to parents. Intl is probably the idealized case: Intl is fully supported ever since it was exposed because being exposed is all it does. The fact that Intl.Segmenter was added much later doesn't matter for Intl—we don't retroactively mark it as partial.

I'm not trying to propose any radical changes here. Instead, I'm trying to describe what we usually do most of the time anyway.

- 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.

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.
<!-- TODO: link to behavioral subfeature guidelines, when available -->

- `"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 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.

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.
Expand All @@ -60,7 +97,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.

Expand Down
5 changes: 4 additions & 1 deletion docs/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down