Add general partial_implementation guideline

[ddbeck]

Summary

This PR provides a general guideline for setting partial_implementation.

Related issues

This continues a discussion started in #26605 (comment).

[github-actions]

Tip: Review these changes grouped by change (recommended for most PRs), or grouped by feature (for large PRs).

[ddbeck]

I suppose one thing that is potentially missing here—or at least not directly mentioned—is some notion of severity: how do we know to use a note alone versus note+partial? A good example of this being a concern is on something like Safari's top-level await bug (#26510) or css.properties.accent-color.maintains_contrast (#26605). This guideline basically says that severity is no matter; if it's inconsistent and difficult to detect as such, we flag it as partial.

My inclination is to adopt a guideline like this, which doesn't require a judgment call on severity, and wait to see if we find a situation where the guideline requires us to do something overtly silly.

[caugner]

LGTM so far, just one nit.

And one possible extension: What about BCD features with subfeatures? In general, we don't set partial_implementation: true on the parent feature, e.g. a CSS property, if the information can be captured on a subfeature, e.g. a CSS property value with partial_implementation: true or version_added: false.

[ddbeck]

And one possible extension: What about BCD features with subfeatures? In general, we don't set partial_implementation: true on the parent feature, e.g. a CSS property, if the information can be captured on a subfeature, e.g. a CSS property value with partial_implementation: true or version_added: false.

If you wish to make this explicit you can, though we don't really document (for example) promoting "version_added": false to parent features. Though a possible coda to this guideline might be:

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 never justifies "version_added": false or "partial_implementation": true for an ancestor feature.

[caugner]

Though a possible coda to this guideline might be:

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 never justifies "version_added": false or "partial_implementation": true for an ancestor feature.

Yes, please, I like that.

[caugner]

Some mostly structural suggestions to ease skimming, reading, and referencing:

[pygy]

As mentioned in #26838 (comment), I think that point 1...

1. The browser's support does not implement mandatory specified behavior.

... should be sufficient to mark support as partial if the missing behavior pertains to accessibility, especially if the lack of support isn't obvious to the layman as the feature seems to work.

Alternatively, it would be nice to be able to prominently warn of accessibility pitfalls, even if it isn't through the partial_implementation field.

[ddbeck]

@pygy For context, this PR is meant to regularize a process we already do here, so I don't think introducing new criteria is in scope. But for completeness, I'll say that I don't believe that deviation from a specification alone is a workable trigger for partial_implementation. Specifications evolve well ahead of implementations, often in highly speculative ways that no vendor has committed to implementing. If we relied solely on spec compliance then many interoperable features would need to be marked as partially implemented despite having no meaningful compatibility risks to developers.

There is a concurrent proposal, #26781, to regularize "behavioral subfeatures" which typically capture the kind of relatively anonymous specification evolution that has gone on for #26838.

That said, nothing in this PR (or the behavioral subfeature PR) should be understood to forbid (non-partial) notes about bugs and other limitations, accessibility or otherwise.

[captainbrosset]

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

[caugner]

I think what's meant here is:

At least one other browser implements this behavior.

[captainbrosset]

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.

[hamishwillee]

@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?

[chrisdavidmills]

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.

[ddbeck]

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.

[ddbeck]

Some responses to @caugner's writing suggestions.

[caugner]

Here is an interesting case from WebDriver BiDi: The browsingContext.print() command takes a parameter page (also in BCD) with two fields height and width, and the spec defines the minimum size as 1x1, and the following:

If the implementation is unable to provide a paginated representation of navigable for any reason then return error with error code unsupported operation.

Before Firefox 133, a size of 0x0 was accepted, and did not result in an unsupported operation error.

I don't think it makes sense to set partial implementation here, even though strictly speaking this behavior

• is mandatory and specified,
• is inconsistent with another browser (Chrome), and
• confuses feature detection results.

Am I missing something?

[ddbeck]

@caugner that is an interesting example! I have a few thoughts on this:

First, in an earlier draft (before I submitted the PR), I had a caveat about how the partial implementation must correspond to "reasonable developer behavior."

I didn't want to allow situations where a contrived scenario would lead to a partial implementation when it would have no real-world meaning. I dropped it from the draft because I didn't quite know how to define "reasonable" but this is the kind of scenario I was thinking of. It doesn't much matter that Firefox and Chrome are incompatible because there's no compelling reason for a developer to expect producing a non-conforming dimensionless PDF to work.

Second, looking into the both the bug and specification text seems to be in response to a challenge when it comes to testing the API (read w3c/webdriver-bidi#473). It seems like the sort of thing that we would have never known about except that:

• WPT revealed the incompatibility.
• The specifiers resolved the matter by revising the specification by narrowing allowed behavior, instead of changing the test or allowing implementers discretion (search the issue for "for any reason").
• The behavior's "defect" was known to BCD only because the vendor proactively provided the information.

At no point in this story was an ordinary web developer involved. This suggests to me that there's the possibility for a fourth condition to be added to the list:

The browser's support inconsistency has a demonstrable real-world negative impact on web developers.

I would take such a condition to mean that there has to be a bug reported (or replicated) by a developer in a situation that impacts real-world users (including preventing the feature from being used with real-world users). Or, in the case of a feature that has not yet shipped (e.g., in a beta), the authors and reviewers of the PR have good reason to believe that it will have that effect when it does ship.

[ddbeck]

We discussed this on a special double-length BCD call today. Main takeaways:

• I need to make it explicit that this guideline describes situations where partial_implementation is required, but not necessarily all situations where partial_implementation is desirable. Other more obscure circumstances came up (e.g., where pre-standards track, single-implementation feature has evolved) where it might make sense to set partial that this guideline doesn't bother with.

• We need to come up with a fourth condition, which weighs developer impact. We know there is something to do with severity, but we don't know exactly how to describe severity just yet. I've asked for input on this point: what's your definition of a bug severe enough to merit partial_implementation?

• Reviewing past practice will help. I'll share a spreadsheet that contains all the partials and their notes, to make this easier to do.

• Once we completed the fourth condition, we talked about introducing a "newly available" guideline, where there would be some period of continued feedback and commentary, before it became a permanent guideline.

[ddbeck]

This came up again in the BCD call today. I've applied a few changes:

• Added a first attempt at a developer significance requirement here as "The browser's support has a demonstrable negative impact on web developers." with a new example where a partial wouldn't be set (a failing WPT with no developer complaints).
• Added "feedback welcome" text at the top of the guideline. In today's call, we talked about adopting the guideline with the understanding it's sort of provisional. We talked about removing this text in 6 months (assuming the guideline survives that long).
• Added a link to this guideline from the docs index.

@caugner and @Elchi3, I'd welcome re-review here. Thank you!

[Elchi3]

Thanks Daniel, this looks good to me 👍

[ddbeck]

From today's BCD call: this still needs a link to this PR, for symmetry with other guidelines. I'll try to get to this shortly.