mdn / mdn/browser-compat-data

Notes with version ranges

Open
#17,857 4 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

meeting agenda schema
Dominant language
JSON
Stars
5.8k
Forks
2.6k
Avg merge
1d 21h
Merged PRs (30d)
186

Description

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:

https://github.com/mdn/browser-compat-data/blob/11afcd744d551964b05c40de52008f8c0db0ee2f/css/properties/align-self.json#L93-L96

Multiple support statements, using version_added and version_removed:

https://github.com/mdn/browser-compat-data/blob/11afcd744d551964b05c40de52008f8c0db0ee2f/api/Element.json#L2651-L2661

The data for the "visibilitychange" change event in https://github.com/mdn/browser-compat-data/issues/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

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reading css/properties/align-self.json and api/Element.json, then compare the visibilitychange example in issue #17854 with the proposed structure here. This is a schema-design task: done requires an agreed versioned-notes structure and consistently updated affected data, but the issue names no tests or implementation entry point.

Written by the indexing model from the issue text.

Assessment

Tech stack
json
Domain
data
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.