Data guideline for all false features

[Elchi3]

What's our data guideline around all false features?

I've been removing irrelevant and amazingly old features that are all false, like:

• the nextid html element Remove irrelevant nextId element data #10550
• Outdated Bluetooth features: Remove never-shipped Bluetooth APIs #9975
• Anything else horribly obsolete at this point. Search for "irrelevant" on https://github.com/mdn/browser-compat-data/releases

However, these are irrelevant features are different from new features that web developers want information on.

• :local-link, as requested in Issue with ":local-link": css rule not working content#4030
• Temporal, for which docs are in preparation.

Rachel says:

Would be good to come up with that way to indicate no support, given the BCD folk don't want features with no support listed.

Do we really want to disallow all false features in all cases?

If the answer is yes, then it leads to some communication problems on MDN: mdn/content#5118 (and potentially on other BCD consumers, such as caniuse)

[saschanaz]

#6809 wants to allow things with tracking issues, since there have been requests to keep items that are expected to be shipped soon-ish. I think the tracking issues should help us see whether the items are still relevant.

[ddbeck]

Do we really want to disallow all false features in all cases?

In general, here's what I want to include:

• features that actually exist, such that web developers can use (or could have, in the recent past) in some widely-available browser (including pre-releases)
• features that are in active development, such that a developer could legitimately want to know whether the feature is available today or when they might use it in the near future (e.g., a feature that a developer may have seen in a demo of a running browser)
• features that have a live prospect of becoming a released feature, such that a developer might have good reason to believe that the feature will soon be in active development (e.g., there's both a specification and one or more vendors have made some expression of interest in implementation)

Here's a scenario I want to avoid: It happens from time to time that someone comes to BCD with a PR to add all-false data for their pet draft specification, with zero evidence that any browser is considering implementing it. From a web developer perspective, that's not data about the web platform so much as it is web platform fan fiction.

So I'm supportive of the idea that all-false features are forbidden, but all-false with notes to relevant bugs/intents are not. #6809 is a step toward implementing that practice, though there's a little piece missing: because anybody can open a bug, we need a guideline to set expectations for sufficient evidence to sustain an all-false-with-notes feature.

[ramiy]

Do we really want to disallow all false features in all cases?

We don't have to disallow all-false features, we can just change the view/result of the compat-macro for missing JSON files.

---

Correct me if I am wrong, but you are trying to avoid a situation were contributors add all-false JSON files for planned features that currently have no browser compatibility.

I don't think it's a technical issue, I think there is a problem with MDN/BCD workflow. If you understand why developers add all-false data, you can make them stop doing that.

Currently, when you create a new page for your favorite new feature, the "Browser compatibility" section shows the following message:

This notice is a call to action to add Browser Compatibility Data. I can safely guess that most MDN contributors don't know BCD guidelines and policies, they just want to document the feature.

We can't force everyone read the rules and follow the guidelines but we can change the {{Compat}} macro output for non-existing values. If compat-macro will display the following view for features that has no JSON file in BCD:

Contributors won't try to add new JSON files with all-false. There won't be any need to add this data as we get the desired result for the feature browser compatibility.

Note 1: I could be complete wrong, I'm talking from my perspective as MDN contributor.

Note 2: If there are other platforms that are consuming BCD data, you need to check their workflows too.

[ddbeck]

It's true that this could be ameliorated a bit on MDN by defaulting to or having an opt-in path to an all-false table for future features. That would be a partial solution on MDN, though it leaves some big holes for driving specification tables (from BCD's spec_url) and status banners (from BCD's status.deprecated, etc.).

It would also push this problem onto consumers. For example, MDN would report all-false, while (I assume that) caniuse would not mention that feature at all.

In any case, I want a guideline because we've been trimming features from BCD and it'd be nice to have a real guideline to cite, rather than saying stuff like, "well, usually…". 😆

[foolip]

I've been removing all-false features and would be happy if it was just not allowed in BCD.

[foolip]

Does anyone have a script for listing the remaining all-falsy (false or null) features?

[saschanaz]

#6809? You can tweak it a bit to include null.

[ddbeck]

A couple weeks ago, @Elchi3 and I had a chat about this topic, partly stemming from what's ultimately reflected in #11813: some web features (in this case, WebXR) would be all false in our data set, even though they're supported somewhere. Or as Florian put it better and more succinctly: some things are "false for all [BCD] browsers but not false for the Web."

This raises another possible exception to the all-false rule: stuff that's implemented in browsers/engines that aren't in BCD. Because that's, by definition, hard to track, I suspect we'd only want to make that exception for features which have a valid spec_url.

[Elchi3]

Thanks Daniel! In #11813 I'm exercising the idea of allowing all-false features and I would like to land it even though it would be all-false. Some rules I can imagine for landing all-false entries.

1. We are forced to provide spec_urls with fragment ids that aren't 404 (Mike checks BCD spec links regularly, so if an all-false feature is removed from specs, we would notice because the provided spec_url 404s and at that point an all-false feature needs to be removed again).
   1.a. The above rule does not apply when there are no other features of this spec with implementation yet. Say there is a new ClockworkOrange API and someone proposes to add 125 all-false features to BCD. This doesn't work. It is too early to add all this in. We don't know where this entire spec is going. However, if it is about adding 2 features from a spec that already saw implementations for other features and that is present in BCD, then it is fine to add the missing features even if they are all-false.
2. There are browsers that we don't cover in BCD yet (Deno, Oculus, QQ, ...) and they are shipping features. So, there aren't actually all-false in the wider sense. Ideally, there is an open issue about adding said browser to BCD when this is the case.
3. Linking to bugs that proof implementation progress and interest. If a feature is going to be available at some point, false statements should link to implementation bugs. These references are useful as they can be checked if implementation has either happened or has been abandoned.

So, I'm thinking 1. is always needed and if additionally either 2. or 3. are given, then all-false features are allowed. I'm curious to hear what other people think, though.

[foolip]

I don't really get the case of other browsers that aren't in BCD supporting a feature. There would be no place to add a note about that, so how would we keep track of this fact and prevent the features from being removed or flagged by a future lint?

[Elchi3]

how would we keep track of this fact and prevent the features from being removed or flagged by a future lint?

We probably won't keep track of this but have a goal to add the supporting browser to BCD.
Maybe this point is mood and too specific to the issue (#11813).

[ZhangYiJiang]

I'm a contributor adding #12125 and would like to provide a perspective for why I think it would be useful to have an all false row in this case.

The feature I'm looking at is Input Event, whose specifications has two levels, and the main page (https://developer.mozilla.org/en-US/docs/Web/API/InputEvent) links to the level 2 specs. From reading the current compatibility table I would thus expect all conforming browsers to support both levels, but in reality level 2 is fairly new and only Safari has partial support for it. The alternative would be to explicitly split out level 1 and level 2 as rows, but it would also be nice to be able to see more granular support.

[saschanaz]

the main page (https://developer.mozilla.org/en-US/docs/Web/API/InputEvent) links to the level 2 specs.

Shouldn't it link to both level 1 and 2 when both are active?

Level 2 items will eventually be merged to level 1 (e.g. w3c/input-events#115 (comment)) so support items should be granular than that to prevent future confusion.

[ddbeck]

@Elchi3, @foolip, @gsnedders, and I had a chat about this topic yesterday. Some highlights on the shape of the problem itself:

• I expressed some skepticism about all-false not being the problem per se. Instead, I think the problem is weeding out real features—even those not yet shipping—from more speculative or forgotten ones.
• Sam highlighted the importance of some all-false features: in some cases, it's nice when BCD can say that something is not supported, rather than simply unknown to BCD.
• I noted that there's a constellation of signals that would identify a real feature (shipping, implemented behind a flag, in an active spec, etc.) and some that would identify ghost features (e.g., removal from a spec). The question is, what signals matter? What's the rule for inclusion/exclusion?

Toward actual solutions, this stuff came up:

• Florian noted that sideshowbarker has already done some work on checking spec_url fragments, so it may be possible to detect, with some granularity, whether a spec has dropped or substantially altered a feature.
• Philip suggested that it would be good to have some concrete examples of all-false but still desirable features to draft guidelines around, rather than trying to work abstractly.
• Philip also suggested that the harms of having all-false would be reduced if all-false (or otherwise poorly supported features) were grouped away from mainstream features (to this point, I promised to bring this up with MDN product and design folks).

I think making a list of good and bad all-false features is probably a good next step.

[gsnedders]

Sam highlighted the importance of some all-false features: in some cases, it's nice when BCD can say that something is not supported, rather than simply unknown to BCD.

A concrete example here is I was curious about what the image-resolution property was; and it is documented on MDN but without any browser compat data.

My concrete belief remains that having everything that appears in a spec (or, more realistically, in a spec in browser-specs) is reasonable, even if the answer is "nothing supports it".

[saschanaz]

Hmm, in that case what should happen when no browser intend to implement something but only some non-browser software do? I believe this is the case for at least one CSS property (but I don't recall which one it is).

[gsnedders]

Hmm, in that case what should happen when no browser intend to implement something but only some non-browser software do? I believe this is the case for at least one CSS property (but I don't recall which one it is).

I'd still say we should document that, because someone might see it in a spec and wonder where it is supported. (I'd presume it's something print-media related?)

[saschanaz]

I'd presume it's something print-media related?

Exactly.

[saschanaz]

because someone might see it in a spec and wonder where it is supported

Both Bikeshed and ReSpec supports inline BCD data table; I think those tools should assume the lack of BCD data as no support and render the table as such.

(Should Yari do the same? 🤔)

[gsnedders]

because someone might see it in a spec and wonder where it is supported

Both Bikeshed and ReSpec supports inline BCD data table; I think those tools should assume the lack of BCD data as no support and render the table as such.

(Should Yari do the same? 🤔)

That to me seems like a significant assumption!

Hopefully we aren't adding many things to specs that never get any implementation, hence I don't think it's too burdensome to add them.

[saschanaz]

Yeah, but I think several of them may get removed without any implementation and be forgotten, requiring mass cleanup after some time.

[foolip]

For features that are in a spec but for which there's no implementation activity at all yet, I think those shouldn't be in MDN or BCD. I agree it could be useful for browser vendors or people involved with standardization, but these features don't exist for web developers, and it seems to me a net negative for developers to document these features. I think I'd be a bit annoyed if I saw a feature that might solve a problem for me, read some documentation, and then learn that it's not supported anywhere.

[ddbeck]

(Should Yari do the same? 🤔)

I think this would be particularly hard on contributors to MDN. This would mask an incorrectly typed feature identifier as unsupported, when it's really an error. If we want to allow presumptive all-false features on MDN, then it's probably best if we make that an explicit choice for authors, rather than an assumption.

That's a possible route forward, but it will require us to have a similar discussion for MDN. When do we cover stuff? When do we drop things? Perhaps that should be an editorial decision managed separately from inclusion in BCD; I'll raise this in the next editorial meeting, to figure out the mood toward that idea.

[gsnedders]

I think I'd be a bit annoyed if I saw a feature that might solve a problem for me, read some documentation, and then learn that it's not supported anywhere.

One option is for Yari to have a clear note at the top of any page it had for a feature unsupported in any browser, and similarly other consumers of BCD could make their own decisions about what to do with all-false features.

I stand by my view that there is value in having it documented, though what consumers of BCD do may well depend on their individual audience expects.

[ptomato]

For features that are in a spec but for which there's no implementation activity at all yet, I think those shouldn't be in MDN or BCD. I agree it could be useful for browser vendors or people involved with standardization, but these features don't exist for web developers, and it seems to me a net negative for developers to document these features. I think I'd be a bit annoyed if I saw a feature that might solve a problem for me, read some documentation, and then learn that it's not supported anywhere.

I get this for sure, but conversely I hope that adoption of a feature into MDN can be started in parallel with implementation activity. From my perspective as someone involved with the Temporal proposal, it would be a shame if an extensive feature like Temporal were to be shipped in browsers and available for developers, and only at that point would the editorial process of reviewing the MDN documentation start.

[foolip]

@gsnedders if something is done on the MDN side to either hide these features entirely, or put them at the bottom of compat tables, then my main concern would be addressed. There would still be a challenge in deciding which all-false features should be added to BCD, since there are many are unlikely to ever get implementer interest, but that's seems doable to write down as a guideline.

@ptomato I agree that starting the documentation process well before something ships is a good idea. If there were a way to do that "behind a flag" in MDN and BCD there would be no tension here at all. And for anything that's behind a flag in some browser, it's already possible to add that to BCD and MDN, not a case of all-false features. Or are there parts of Temporal that have no implementation at all yet which are still important to add to MDN/BCD?

[ptomato]

No, it's more that implementation is in progress in Chrome, Firefox, and Safari, but Temporal is the largest TC39 proposal ever (we think) so both the implementation and the merging of documentation into MDN will take nontrivial amounts of time.

[saschanaz]

Could be great if MDN can have a draft document explicitly marked as such in that case, or even just a draft PR with auto-rendered preview. (mdn/content already previews PRs)

[foolip]

@ptomato I agree there's an interesting process problem to solve here, namely how to produce high quality documentation that's ready to go at the time a feature first ships in some browser. But if there is implementation in progress now, it doesn't seem like a case of an all-false feature, since experimental features behind flags can be represented in BCD. I take this issue to be about features for which there simply is no code written in any browser engine repo.

[ddbeck]

In the most-recent MDN editorial call that I attended (just over a week ago), I put, roughly, this question to authors: should MDN cover something that BCD says is all-false? This provoked some interesting responses, which I'd say had three main themes:

1. Sometimes it's helpful to cover unsupported features because of reader demand or author convenience.

   For example, Rachel Andrew said that CSS is front loaded by specification, followed by a long (and sometimes incomplete) process of implementation. This means that web developers may know about CSS features before they're supported and get annoyed or confused when they're in the spec, but unmentioned on MDN. I believe container queries were a (former) example of this phenomenon.

   Similarly, there were complaints that sometimes it's necessary to awkwardly avoid mention of unimplemented features, where it would be easier to cover certain topics with frank acknowledgement of unimplemented features.

2. Unsupported features create unwanted process questions for authors.

   Authors don't want content for features dropped from specifications to stick around. Who would clean up such content from MDN? What validation might trigger cleanups (e.g., spec URL validation)?

   (Additionally, there's a worry about having to document unimplemented features, given there's enough to do as it is. Though we don't document everything that's supported, so I don't think this is especially relevant, at least not yet.)

3. Data rendering is a problem for all-false features.

   Like our discussion here, there was talk of readers being surprised by unimplemented features (since you have to scroll to the bottom of the page to find out about it) and concerns about clutter in compat tables with a large proportion of unsupported features. This is important, but not strictly related to what BCD covers (or even the compat tables themselves).

---

OK, now I'll editorialize a bit with my takeaways:

The editorial discussion immediately gravitated to content's relationship with specifications. I'd go so far as to say that, from the content perspective, the scope of the problem is limited to features that are specified but unimplemented. To me, this suggests that:

• We could ban all-false features without valid spec_urls today.

• We could solve most of parts 1 and 2 with effective weeding of features in abandoned specs or those dropped by active specs.

  For example, removing features from specs dropped from w3c/browser-specs (which we'd have to do to upgrade w3c/browser-specs anyway) and removing features with broken URL fragments for all other specs (I believe Mike Smith has done some work in this area already).

• We could set a data guideline requiring that a committer on mdn/content OK the introduction of an all-false feature, where no content exists (or is expected to exist soon, in the case of WIP PRs) for the feature on MDN itself.

That leaves part 3, displaying the data usefully by warning about all-false features at the top of a page and pushing all-false features to the bottom of compat tables. I think the latter part could get on the roadmap with other visual improvements ongoing for MDN somewhat soon, but the former would be a new addition. That said, I'm not sure that either of these are true blockers to setting policy for BCD. In some cases (e.g., recently removed features), these problems already exist. And we certainly don't have to solicit all-false data, in the mean time.

[jpmedley]

This notice is a call to action to add Browser Compatibility Data. I can safely guess that most MDN contributors don't know BCD guidelines and policies, they just want to document the feature.

One fix might be that such pages could be excluded from the site render when everything is false. You would want a report or something similar listing items in this state so that you could clean them out occasionally. This would create a space for more drafting before a feature is released. Part of the reason for the enormous backlog of undocumented features the tendency of developer shops to build and move on/forget.

Or as Florian put it better and more succinctly: some things are "false for all [BCD] browsers but not false for the Web."

As stated above, this is more common with CSS than with API. Regarding APIs be careful . There's a razor thin window between stabilization of new spec churn and implementation in a browser.

I noted that there's a constellation of signals that would identify a real feature (shipping, implemented behind a flag, in an active spec, etc.) and some that would identify ghost features (e.g., removal from a spec). The question is, what signals matter? What's the rule for inclusion/exclusion?

I can take this back to the Chrome Status crew as a use case for how we display that something is shipping or is being removed. In our case, it's not enough to show that something is shipping in a certain version. The status of a feature with regard to Chrome's approval process isn't currently shown, but I believe we're planning to.

My concrete belief remains that having everything that appears in a spec (or, more realistically, in a spec in browser-specs) is reasonable, even if the answer is "nothing supports it".

Specs get out of date and sometimes when vendors get around to implementing lagging features they no longer make sense so they drop them. I wish I had stats on how often this happens. I don't.

I hope that adoption of a feature into MDN can be started in parallel with implementation activity. From my perspective as someone involved with the Temporal proposal, it would be a shame if an extensive feature like Temporal were to be shipped in browsers and available for developers, and only at that point would the editorial process of reviewing the MDN documentation start.

I agree, but I think resource problem is blocking any policy solution we could craft. There aren't enough people documenting platform changes.

We could solve most of parts 1 and 2 with effective weeding of features in abandoned specs or those dropped by active specs.

This is actually another mine field. Dropped, but previously implemented features must be deprecated and removed in browsers. We do this in phases in Chrome so that site owners have time to rewrite code. Developers may need to refer to what an old feature did to account for all their use cases in new code. (Archive is still a thing, right?)

We could set a data guideline requiring that a committer on mdn/content OK the introduction of an all-false feature, where no content exists (or is expected to exist soon, in the case of WIP PRs) for the feature on MDN itself.

I really like this idea. This is best accomplished with the help fo reps from vendors since they are best able to read their internal tea leaves.

[saschanaz]

We could set a data guideline requiring that a committer on mdn/content OK the introduction of an all-false feature, where no content exists (or is expected to exist soon, in the case of WIP PRs) for the feature on MDN itself.

Can this be made linter-friendly, requiring a new field that links to the relevant comment/thread? 👀 I still wonder #6809 can be used for this.

[foolip]

We could set a data guideline requiring that a committer on mdn/content OK the introduction of an all-false feature, where no content exists (or is expected to exist soon, in the case of WIP PRs) for the feature on MDN itself.

Can this be made linter-friendly, requiring a new field that links to the relevant comment/thread? 👀 I still wonder #6809 can be used for this.

If there's a this_all_false_entry_deserves_to_be_here_because field then it would indeed be trivial for a lint to check this.

[gsnedders]

OK, now I'll editorialize a bit with my takeaways:

The editorial discussion immediately gravitated to content's relationship with specifications. I'd go so far as to say that, from the content perspective, the scope of the problem is limited to features that are specified but unimplemented. To me, this suggests that:

• We could ban all-false features without valid spec_urls today.
• We could solve most of parts 1 and 2 with effective weeding of features in abandoned specs or those dropped by active specs.
  For example, removing features from specs dropped from w3c/browser-specs (which we'd have to do to upgrade w3c/browser-specs anyway) and removing features with broken URL fragments for all other specs (I believe Mike Smith has done some work in this area already).
• We could set a data guideline requiring that a committer on mdn/content OK the introduction of an all-false feature, where no content exists (or is expected to exist soon, in the case of WIP PRs) for the feature on MDN itself.

Honestly I'd like to see how things go if we just do the first two, personally?

[ddbeck]

OK, I think the next step here is to talk to @sideshowbarker about what needs to happen to bring spec_url validation to BCD.

[sideshowbarker]

I think the next step here is to talk to @sideshowbarker about what needs to happen to bring spec_url validation

#11430 has a spec-URL linter from @queengooborg that I think is ready for merging

[queengooborg]

Coming back to this about a year later, I think that we've pretty much established that all-false features aren't allowed. We have a guideline that says that all-false features with an abandoned spec can be considered irrelevant and removed, but we've also been saying "no" to PRs that add features set to all false, and recommending content writers use the spec_url meta tag.