Document the various scripts

[gsnedders]

At least from the names, it's not clear what the difference between update-bcd and add-new-bcd do. It would be nice to actually document what all the various scripts do, and how to run them.

If I were to have, locally, results for Safari 14 and Safari 14.1, how would I create a diff for BCD for changes in 14.1?

[foolip]

update-bcd.js is the script you'll want to use. add-new-bcd.js only adds empty support statements for missing features which update-bcd.js could then fill in.

So if you have browser-compat-data checked out next to this repo, you can try node update-bcd.js safari-14.json safari-14.1.json and see if that produces any useful changes in BCD.

And yes, this should be documented.

[foolip]

To make this more concrete, I have results for iOS 14 and 14.5 now so that we can discuss specifics about how to use the update-bcd.js script:
https://github.com/foolip/mdn-bcd-results/blob/15c69c28e6e66c9ae65bc7dd1b62827d2e0517ae/2.0.1-safari-ios-14.0-ios-14.0-f0d6494a81.json
https://github.com/foolip/mdn-bcd-results/blob/15c69c28e6e66c9ae65bc7dd1b62827d2e0517ae/2.0.1-safari-ios-14.5-ios-14.5-7e3ab9f02e.json

With those running node update-bcd.js ../mdn-bcd-results/2.0.1-safari-ios-14.0-ios-14.0-f0d6494a81.json ../mdn-bcd-results/2.0.1-safari-ios-14.5-ios-14.5-7e3ab9f02e.json results only in "≤14" changes.

The first problem is that version "14.5" isn't in BCD. I've sent mdn/browser-compat-data#9240, but making that changes locally in ../browser-compat-data/browsers/safari_ios.json is sufficient.

Then, the script produces a bunch of "14.5" updates, but also lot of "≤14" because of things that were already in Safari iOS but BCD isn't updated yet.

I'm thinking that maybe a --added=14.5 command line argument would do the trick here, to only act on statements which are setting version_added to "14.5". @gsnedders do you think that sounds right?

[foolip]

I'm documenting npm run update-bcd in #1019.

[gsnedders]

I'm thinking that maybe a --added=14.5 command line argument would do the trick here, to only act on statements which are setting version_added to "14.5". @gsnedders do you think that sounds right?

No preference; I'm happy manually adding things to browsers/*.json as needed. It might be worthwhile changing the logic for major/minor versions for Safari at least, however?

[foolip]

It might be worthwhile changing the logic for major/minor versions for Safari at least, however?

The tricky part is iOS versions, which are used in BCD instead of the Safari version.

Because the iOS version that includes Safari N.1 changes over time, it's not safe to assume that a version larger than current stable is a new release.

However... I just realized we could look at both the Safari version and the iOS version in the UA string and thereby know that iOS 14.4 should be "14" in BCD but 14.5 is new and shouldn't be treated as 14.

I'll try tweaking this logic.

I'm OOO next week however so I might not do any work on BCD then.

[foolip]

This is the last open issue in this repo, which I'm sunsetting in favor of https://github.com/openwebdocs/mdn-bcd-collector.

I've filed mdn/browser-compat-data#20820 which doesn't totally cover this, but if you also think you'll want to run any scripts in the mdn-bcd-collector repo itself, please file an issue at https://github.com/openwebdocs/mdn-bcd-collector/issues.