search

bcgov / bc-wallet-mobile

BC Wallet to hold Verifiable Credentials
Apache License 2.0
60 stars 49 forks source link

Publish Release Notes #109

Open cvarjao opened 2 years ago

cvarjao commented 2 years ago

How do we create, maintain, and publish human readable release notes so users can see a relevant "what's new" for each new version

WadeBarnes commented 2 years ago

GitHub has the ability to auto-generate release notes for you. Here is an example (no updates where performed to what was generated); https://github.com/bcgov/aries-vcr/releases/1.9.0

The notes are based on the activity since the previous release. The trick would then be to title the PRs descriptively (which should be happening anyway).

amanji commented 2 years ago

I am a huge proponent of this. Commits and PRs really just need to conform to a specific template or set of guidelines and they just get rolled up in a release.

cvarjao commented 2 years ago

That looks very good! The app release notes get published to the app stores. Those notes make sense to me. Will they make sense to the average user using the app? Or do we write commits/PRs with the mindset that it needs to be somewhat understandable by the average (non-tech) user?

WadeBarnes commented 2 years ago

I think it makes sense to write commits/PRs with the mindset that it needs to be somewhat understandable by the average (non-tech) user. At least for the summary/title. If you can provide a good summary that's typically all a non-technical user needs.

cvarjao commented 2 years ago

Would you recommend adopting Conventional Commits, or some variation of that?

swcurran commented 2 years ago

I would vote for using Conventional Commits, in conjunction with making the title understandable. I've seen the CC standard being used in other organizations and they are indeed helpful for creating release notes, but without a thoughtful title, they are not useful.

I discovered the "Generate Release Notes" feature in the last ACA-Py release. We already do a ChangeLog that we produce (mostly) manually to try to help the target audience (as Wade noted above). The use of CC would help a lot with that -- especially the use of "BREAKING CHANGE". Then, I used the GitHub feature in the release tag to provide a purely mechanical list.

Unless we push hard on the devs to put in great PR names, the auto-generation alone will be insufficient, even with CC.

But -- definitely agree we should try to push for the use of CC.