css-meeting-bot
commented
9 months ago The Browser Testing and Tools Working Group just discussed Generate browser-compat-data from CDDL.
The full IRC log of that discussion
<jgraham> Topic: Generate browser-compat-data from CDDL<jgraham> github: https://github.com/w3c/webdriver-bidi/issues/619
<jgraham> whimboo: A while ago I asked about documenting APIs on MDN. We delayed this. Classic has a few commands documented. Might not be trivial to document everything, but we could focus first on BCD. This would allow filling in the tables on MDN with compatibility across versions. Clients could also use this data. This would be a good start for documentation. Tools like e.g. VSCode could also consume it.
<jgraham> whimboo: All the data is in JSON files. Might be work to manually create it. But we have CDDL blocks which are used to generate TS in the Chromium implementation. We could maybe use that generation code to generate BCD data and keep it up to date.
<jgraham> whimboo: Would like to get some feedback on this. We could start with some manual work if that's easier.
<jgraham> q?
<jrandolf> q+
<jgraham> ack next
<MaksimSadym> q+
<jgraham> jrandolf: CDDL has a native representation for JSON. The tool for generating TS is not canonical, but there is one for JSON. The parser can validate JSON files. I'm not sure if the tool fits for this scenario.
<cb> q+
<jgraham> whimboo: The main question is whether this would be useful at all.
<jgraham> ack next
<whimboo> whimboo: everyone of us would have to update the json files for the release versions in their browser
<jgraham> MaksimSadym: Are we talking about generating JSON from the spec, or about the browser returning the protocol version it supports?
<jgraham> whimboo: we need a list of all the commands and events that we support. Generating full documentation is harder. Would like to know which version of the browser implements each API.
<jgraham> ack next
<jrandolf> q+
<jgraham> cb: From the client perspective this would be very helpful either as a file or as an endpoint in the driver. In the client we could help them understand why a command isn't working.
<gsnedders> q+
<jgraham> jgraham: BCD already exists. The request is to be able to generate that specific format from the CDDL
<jgraham> ack nex
<jgraham> ack next
<jgraham> jrandolf: The problem to solve is building a browser compat table? Isn't the point of these meetings to standardise and implement everything in BiDi? What do these files actually specify? That someone doesn't implement a specific feature?
<whimboo> current source of BiDi support comes from https://docs.google.com/spreadsheets/d/1bkiPU5eDBCqFkx5p_VSBx_OK8gy9TeHRKQVPHKMATGQ/edit?pli=1#gid=0
<jgraham> jgraham: No, the point is which version of the browser first implements a BiDi feature
<jrandolf> Good point
<jgraham> gsnedders: Other specs might also define custom extension points e.g. permissions. In a browser that didn't support permissions that extension wouldn't be implemented, and that's useful to document. Might add more features in the future and existing implementations might not support them.
<jgraham> gsnedders: The current BiDi implementations use CDDL directly? [not really]
<jrandolf> q+
<jgraham> gsnedders: So there's not just a way to get the copy of the CDDL emedded in the browser version to work out which APIs are being implemented. But we could generate empty implementations from the spec and maybe automatically add browser data from implementations that use CDDL directly.
<jgraham> ack next
<jgraham> ack next
<jgraham> jrandolf: I think it would be nice if other vendors also used the CDDL as a way to version what they do. Could use that to generate a compat table if they trim the CDDL to what they support.
With the help of the
browser-compat-data(BCD) project clients can retrieve compatibility data for Web technologies as machine readable data (JSON). This information is embedded in various tools like MDN Web Docs, browser internal debuggers, VSCode and others. As an example see:https://developer.mozilla.org/en-US/docs/Web/API/Element#browser_compatibility
This can be helpful information for developers of WebDriver clients, and testers. With such information they would know which APIs (commands, events, etc...) are available overall, and when those have been added, deprecated, or removed in individual browsers.
Some time ago I've already filed an issue on that repository to get the data added for WebDriver BiDi: https://github.com/mdn/browser-compat-data/issues/20207
As referenced in this issue the location of our data could end-up at: https://github.com/mdn/browser-compat-data/tree/main/webdriver/bidi/
Updating the data manually is quite a bit of work. So maybe we can also generate the skeletons automatically by parsing the CDDL definitions and generating the appropriate JSON files, and maybe also update existing ones.
Given that @jrandolf wrote already a tool to generate TypeScript it might be not too hard to generate the appropriate JSON files.
While manually adjusting changes and sending PRs for the beginning, I could imagine a GitHub Action that could do that automatically. But lets defer this for now...