Research: Release Notes! What are the *Best* examples we can find?

[nelsonic]

What are the best examples of release notes you can find for any App? The best release notes are the ones that:

1. Clearly communicate what updates were made in the latest release including: A. Feature improvements - shiny new things people really wanted B. Bug-fixes - things that were broken C. performance enhancements D. celebrate the people who made the release possible
2. Link to the issue(s) & PRs where the work was captured & performed
3. Screen Recordings of the features that people can play-back to learn how the feature works!

Todo

Please find and share examples and be as specific as possible with:

• [ ] screenshots, screen recordings, videos where available
• [ ] copy-paste text and
• [ ] directly link to the example where possible.

[LuchoTurtle]

Haven't yet researched "good release notes" but the common practice seems to follow a template that is systematically updated on every release. Big projects like Three.js seem to be using this format, which credit each contributor along the way.

I feel for dwyl's case, having a release-drafter, combined with a tool like Chronicler will make release notes much easier and automatic (for the most part, it will always need a human touch).

We should adopt conventional commits, as it paves the way to generating changelogs quite easily.

We can follow GitLab's guide when writing a release template (or KeepAChangelog's).

[nelsonic]

@LuchoTurtle the Three.js release notes: https://github.com/mrdoob/three.js/releases/tag/r148

A bullet point list with links. Those links are mostly to PRs. The PRs are themselves just referencing issues e.g: https://github.com/mrdoob/three.js/pull/25165

https://github.com/mrdoob/three.js/issues/24711

Yes, Three.js is a good Open Source project with many people using it. 👍 But these release notes are very much only interpretable by fellow developers, they aren't written for regular people. Perhaps it's because non-technical people don't tend to use Three.js...

But this is definitely not what I have in mind. I want the release notes to tell a visual story. That means either a Video that people can watch to see what new features were added. or a GIF that shows just the section that was added. These can initially be hand-made by the person who is leading the release/update. But longer term, we should figure out how to automate this or at least delegate it to a VA.

A list of links is the "ordinary". We see this everywhere. 🥱 #boring https://github.com/FreeCAD/FreeCAD/releases/tag/0.20.2

“The difference between ordinary and extraordinary is that little extra.” ~ Jimmy Johnson

I'm not saying I have the answer yet! That's why I opened the issue to research. We can certainly start with a set of links on a page. But we need to know what our end-goal is. And that is to have something "Wow!" 😍 Something that busy non-technical people take 5 mins out of their day to read/watch.

[nelsonic]

The Miro updates are a good example: https://miro.com/changelog/

They often include GIFs of the functionality described in the release. Again, not saying this is the "Right" way to do it, but it's far more non-technical person friendly than a list of links.

[nelsonic]

Please see: https://www.launchnotes.com/blog/release-notes-examples#miro