Notes with version ranges

[foolip]

Notes are used a lot in BCD to inform readers about specific bugs that affect certain versions of a browser. There are two predominant styles for this, shown by example here:

A note including the affected version:

browser-compat-data/css/properties/align-self.json

Lines 93 to 96 in 11afcd7

	"firefox": {
	"version_added": "20",
	"notes": "Before Firefox 27, only single-line flexbox is supported."
	},

Multiple support statements, using version_added and version_removed:

browser-compat-data/api/Element.json

Lines 2651 to 2661 in 11afcd7

	"chrome": [
	{
	"version_added": "22"
	},
	{
	"version_added": "1",
	"version_removed": "22",
	"partial_implementation": true,
	"notes": "Only supported for <a href='https://developer.mozilla.org/docs/Web/API/HTMLElement'><code>HTMLElement</code></a>, not all <code>Element</code> objects, such as <a href='https://developer.mozilla.org/docs/Web/API/SVGElement'><code>SVGElement</code></a>."
	}
	],

The data for the "visibilitychange" change event in #17854 is great example of how complicated things can get with the multi-statement style, requiring repeated notes.

Some issues with the current approach:

• Not consistent
• Versions inside of notes are not (easily) machine readable
• Multiple support statements require duplication when there are overlapping bugs
• Neither style can easily be converted into the style of footnotes on caniuse.com, where there each note has a number, and each release has a number of footnotes. https://caniuse.com/border-image is a good example of this.

I would like us to consider adopting a different structure, where notes can have version ranges independent from the main version_added and version_removed. Mock proposal with the "visibilitychange" case, with simplified notes to make it cleaner:

{
  "version_added": "7",
  "notes": [
    {
      "version_fixed": "14.1",
      "note": "The event is not fired when navigating away from a document."
    },
    {
      "version_fixed": "14",
      "note": "The event does not bubble."
    },
    {
      "version_fixed": "10.1",
      "partial_implementation": true,
      "note": "The <code>onvisibilitychange</code> event handler property is not supported"
    }
  ]
}

cc @Elchi3 @queengooborg

[foolip]

@Fyrd do you have thoughts on what would work best for caniuse.com?

[foolip]

cc @ddbeck

[ddbeck]

I love the idea of adding structure to notes—it's something I've long wished for. There's a lot to be won from structuring notes, both in terms of data quality and consistency and making it work better for consumers.

Thinking aloud here:

• Where do notes go that are introduced after the start of a support statement?

  For instance, suppose a feature was introduced in version 10, a noteworthy bug introduced in version 11, and a fix introduced in version 12.

  One answer is that notes can have full versioning symmetry with support statements (that is, notes have effective version_added and version_removed fields). That would suggest that notes are a practically a parallel structure to support, which is an interesting prospect to say the least. (As an author, it'd be very frustrating to work with a compat-level "notes" key—separately as a peer to "support"—but the principle of the thing is not wrong.)

  If the answer is no, I think we still have the possibility of note duplication (e.g., a bug might persist across multiple support statements), though I'd expect rather less frequently.

• version_fixed implies that notes only describe bugs, which I don't think is quite right (e.g., none of the notes describing APIs moved on the inheritance chain is a bug per se). But it's suggestive of even more structure, to the point of annotating types of notes.

  For example, you might use a strictly-controlled "subject" field to constrain note contents or to require additional fields:

  [
    {
      "subject": "bug",
      "version_removed": "10",
      "note": "The method erroneously returns an integer instead of a floating point number.",
      "citation": "https://bugtracker.example.com/1234/"  // required field for bugs?
    },
    {
      "subject": "spec-change",
      "version_removed": "20",
      "note": "The <code>Example</code> interface itself is not present, but many of the methods are available on the <code>OtherInterface</code>."
    },
    {
      "subject": "misc",
      "note": "This has a surprising, but spec-complaint, behavior."
    }
  ]

  With this sort of structure, you'd open the door to lots of note automation, such as enforcing text style specific to note genres or generating PRs for resolved bugs.

• On the specific matter of note duplication and consistency, I know that a great many notes are duplicates. On the authoring side (i.e., don't expose this to consumers), it might be nice to have notes by reference to a centralized collection:

  [
    {
      "note_ref": "chromium-bug-5678"
    }
  ]

  Where the actual note gets inlined out of a shared notes.json or somesuch (this, to me, is a much friendlier abstraction than "mirror", which is quite opaque). Not only would you get the benefit of all notes for the same topic being the same, but you'd also get the benefit of authoring the notes in one place, where it'd be more obvious that you've written notes in a non-standard style or tone.

[foolip]

#22939 is a good example of the need for this. I needed to use 6 entries in the compat statements array, because the API was both prefixed and unprefixed, and there were two different states of partial support. 2 times 3 is 6.