Feedback wanted: BCD release notes #13229
Comments
queengooborg
added
the
question
|
I'm talking about the GitHub releases not the RELEASE_NOTES.md file. I have subscribed to "Release" notifications of my favorite projects and repositories on GitHub, including this repository. Although it's been some time since I worked on Web projects, I regularly check my GitHub notifications (when there is a blue dot on the bell icon) for these release notes, and I love to see them. It has become like an RSS feed reader for libraries/projects changelog, new features etc. This article is related. As a side note, I have written a GitHub workflow job for one of my own libraries that automatically generates the release notes from the repository CHANGELOG.md file (and also creates the showcase APK) so I do not have to create the release notes for GitHub releases again and by myself. Also, as you probably know, there are ready-to-use GitHub actions like this for that purpose. |
|
I consume the data of this repository for canistop.net using automation, and like @mahozad I’ve subscribed to “releases” notifications. I’m interested by any potentially breaking change in the structure of the browsers data. So, when reading the release note, that’s the single thing I’m looking for. As such, it would be great if the “scope” of each entry could be highlighted. For example, in the 4.0.0 all “notable changes” are listed without distinction. Taking a subset, it roughly looks like this:
I think having just the scope/type of change i front of each entry would help me to scan and picture what the release is all about. A bit like this:
|
|
As a consumer, these release notes are vital but could use a cleanup, imo:
i.e.
becomes
But definitely keep it short and sweet with a link to each PR. I would also recommend including new features and fixes, too, as some people pay pin the package to But, seeing as you're following semver, I would strongly recommend adopting the conventional commits standard and completely automate the process with one of the well established change-log generators:
As impressive as the stats are, I don't think the changelog is the right place for them, perhaps go bananas with it and include a interactive graph in your docs somewhere. I know they're at the bottom of each release but if, like me, you rarely update this package then that's a lot of extra fluff to scroll through when you're jumping several versions (on both https://github.com/mdn/browser-compat-data/releases and https://github.com/mdn/browser-compat-data/blob/main/RELEASE_NOTES.md) |
|
Thanks for the feedback that's already appeared so far. It's quite interesting and valuable! I've made one last call for feedback before we start changing things up, but it sounds like there's lots of opportunities to improve things, even without a lot of effort up front. For example, I generated a list of changes for the latest release (with a very, very rough looking set of shell scripts). cc: @Elchi3 Example generated notes for v4.0.11Removals in this version
Additions in this version
|
|
The most recent release used a mostly-generated process. See https://github.com/mdn/browser-compat-data/releases/tag/v4.0.12. |
|
It's been a while without further commentary on releases. I'm going to close this, though work continues on improving our release process. Thanks, everyone! |
and others
Hi all,
please take a look at the release notes https://github.com/mdn/browser-compat-data/blob/main/RELEASE_NOTES.md
Do you read the release notes regularly?
Which information is useful to you?
Do you make use of the "Notable changes" lists? It often talks about renames and removals like so:
Do you make use of the statistics section?
We would like to automate releases some more and your feedback helps us to determine the importance of the information in BCD release notes. Thanks!
The text was updated successfully, but these errors were encountered: