Support linking to bugs/issues about browser-compat-data

[caugner]

While migrating compat data from MDN tables, I tried to check whether existing version_added data was actually correct / accurate (out of curiosity, and to detect misleading instances of "it works in this version [but I didn't check previous versions]") and found some cases where it wasn't (from what I found).

In this case, references not only would have helped me in this verification process, but providing them also allows me to be transparent about why I came to another conclusion (w.r.t. version_added, which can be hard to determine objectively on a binary scale, cf. discussion about implementation_status) than the people before me that added the data on MDN in the first place.

Regarding the concern about the expectation these references may create, I would argue that BCD is, for one thing, already creating the expectation of providing reliable compat data. But can it really live up to this expectation without providing references that allow verification?

Then again, it's one thing to build these references directly into the schema, and another one to require them as a means of justification for all changes to BCD themselves. In fact, most PRs already seem to include references, and reviewers do (systematically?) ask for sources, if they aren't given already (this might be facilitated with a PR template).

So maybe that's actually the root of the question: Where should we put these references [that inevitably exist already]? Does it suffice to list them in the PR? Should they also be in the commit messages themselves? Or do we also want to provide them in a structured, machine-readable way as part of the BCD?

If I was given the choice, I would probably add them to the data itself, by analogy with Wikipedia.

[Elchi3]

So, I've noticed a few cases:

1. A feature isn't implemented, we then link to the bug that implements the feature, see https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control#Browser_compatibility
   I think this is a good candidate to be in a property called e.g. "implementation_bug".

2. The feature is implemented, we still link to the bug that implemented it, see https://developer.mozilla.org/en-US/docs/Web/CSS/:focus-within
   I think we shouldn't do this. The bug doesn't add value anymore.

3. The feature is implemented behind a pref and thus needs a note anyway. The note should ideally contain the bug that will remove the pref, see https://developer.mozilla.org/en-US/docs/Web/API/Pointer_events/Using_Pointer_Events#Browser_compatibility

4. The feature used to have or has bugs, which almost always need explanation in a note or an own section, so that the reader knows what those issues are/were. See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/toString#Browser_compatibility

I think what I would want is a property called "implementation_bug" (or similar) for case 1 and just notes for the other cases 2, 3, and 4.

[SebastianZ]

Part of the reason I didn't suggest this was that I wanted notes to be treated as plain text

Formatted notes improve the readability and transport more information. Therefore I vote for using/keeping formatting in notes. Though that discussion should probably rather happen in #114.

2. The feature is implemented, we still link to the bug that implemented it, see https://developer.mozilla.org/en-US/docs/Web/CSS/:focus-within
   I think we shouldn't do this. The bug doesn't add value anymore.

I've asked about that some time ago and the consensus back then was tending to keep the bug as reference for the compat data.

In this regard, it would make sense to reuse the implementation_bug property.

Anyway, I'm still not convinced that having a separate property for this is necessary, but I also don't have a strong opinion against it. Regarding the migration from the static contents to the structured data it definitely means more work.

Sebastian

[a2sheppy]

I propose instead the name "implementation_status", which can then have the values:

• "under consideration"
• "partial"
• "not planned"

Or a numeric value, which is treated as a bug/issue number.

[demurgos]

Hi,
I'd like to add that I'd find links to related issues to be useful as sources for the provided data. I am not familiar with the process to update the data you have here, but it would be nice to have the data backed by links. It would be similar to Wikipedia's references. I am not sure how to check the origin of data today.

[wbamberg]

@teoli2003 , can we include this in the new schema proposal?

[teoli2003]

Yes, sure!
A few questions:

1. Do we want to link to issues (read: problem) only?
2. If not, do we want to be able to distinguish between bugs and issues like "Not enabled, this is the enabling bug"?
3. What will happen when a issue is fixed, do we remove the bug # or do we want to store the information that from version X to version Y there was issue Z ?

[wbamberg]

I didn't file this, but my interpretation is that this is for situations where the feature hasn't been implemented yet, or has been partially implemented, but the browser has a bug open to implement it. So the user can follow the bug to get an idea of when it might land.

So it's not just general "bugs associated with this feature".

So it could be an optional extra field, if the feature has no support or experimental (preffed-off) support, like:

{tracking-bug: [url]}

If the feature is fully supported (even if it is buggy!), this isn't ever present. But that's just my interpretation of this.

[SebastianZ]

I think links to bugs should be part of the notes' text as it's currently done on MDN. Note that there may be more than one bug related to a feature and the note can explain the situation better than just a URL.

Sebastian

[wbamberg]

Part of the reason I didn't suggest this was that I wanted notes to be treated as plain text, and then it would be complicated to make them behave like links. And URLs that aren't links just seem silly.

I agree though, that if these bugs are just general bugs around the feature, or if there's any nuanced explanation to be done, then unstructured notes are the right way to go. But it seems that in many cases there is one tracking bug for a feature, and in these cases it seems that it would be helpful to give them a place in the schema so they can be consistently exposed to users.

[a2sheppy]

I like the idea of using a property or properties for bug links by inserting a "bug-url" field or similar anywhere it makes sense.

[jpmedley]

I'm concerned about creating the expectation that MDN is a place that has or is trying to have complete bug information. Having an explicit place for it would give that impression. I'm not sure that accomplishing it is practical.

[teoli2003]

I think @jpmedley has a really good point: there is no way we can have this information complete.

[chrisdavidmills]

Yeah, it would be a nightmare to try to accurately convey all this information, for all browsers we provide BCD on.

My thought is that (at least for Fx), as long as we have the version_added field filed in accurately with a version number, we should be able to then go and look up the bug details in the developer rel notes (e.g. https://developer.mozilla.org/en-US/Firefox/Releases/60). All added details should be put inside the documents.

that way we could keep the bug details there, and keep the BCD cleaner.

[Elchi3]

As noted above, there are different situations where we have added bugs to the compat tables or compat data. Always adding bugs for all features stored in this data set is indeed a non-goal.

I still think adding links to bugs for situation 1, like done here https://github.com/mdn/browser-compat-data/blob/master/api/NavigationPreloadManager.json#L24, is useful. That could be in the note like we've done that for now for NavigationPreloadManager, or we introduce implementation_bug.

[chrisdavidmills]

Yeah, I could see that being useful, as long as it isn't mandatory. It would need to support arrays, so that we could have implementation bugs included from multiple browsers.

[Elchi3]

Certainly not mandatory and only really used when there is no support, but you want info whether or not the vendor considers adding it and where they are with that.

I would see this at the browser level and maybe it could just be "implementation".

"chrome": {
  "implementation": "123456",
  "version_added": false
},
"edge": {
  "implementation": "under consideration",
   "version_added": false
},
"firefox": {
  "implementation": "123456",
   "version_added": false
},

Once the bug / the status info is resolved, this gets removed and version_added has a version:

"chrome": {
  "version_added": "60"
},
"edge": {
  "version_added": "18"
},
"firefox": {
  "version_added": "66
},

(I guess this would also help https://platform-status.mozilla.org/ to just use this repo as its underlying database.)

[chrisdavidmills]

Cool, this all makes sense to me, thanks for the further explanation. I am happy with this as a proposal.

[a2sheppy]

I also agree that this should only be used to flag bugs that are directly related to the implementation state of the feature, and should not be used for any other purpose or to note the bug that implemented the feature.

[myfonj]

For those confused (like me) why data from impl_url JSON fields are not yet visible in actual MDN BCD tables, it is a YARI feature under PR mdn/yari#6376

(There are few dozens of entries with impl_url filled; for example I wondered why I don't see those merged with e.g. #17353 at https://developer.mozilla.org/en-US/docs/Web/CSS/:has#browser_compatibility )