Notes with version ranges
Nobody has claimed this yet.
- 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:
Multiple support statements, using version_added and version_removed:
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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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