Release Notes Guide - NASA-PDS/nasa-pds.github.io GitHub Wiki

Release Notes Guidelines

We are using GitHub's automated Release Note generator and tweaking as appropriate. The release notes use Pull Request titles to generate the release notes. So this would require the developer to make a pull request title that is user-friendly. We can think about this as the story/bug ticket is what we want to do or need to fix, while the PR describes what was done in a user-friendly fashion. Our CHANGELOGs include all the issues closed, but the titles (e.g. user stories), don't really tell the user what has been done from their perspective. For example, a requirement issue title As a user, I want to execute content validation against every nth file is great, but the user has no idea what that means for them or how to use this new story. But if we had a PR title that read New --everyN flag for spot checking every nth file, the user would at least have a basic idea of what they can look for that is new.

For "parent repos" that include numerous components (e.g. registry, pds-api, validate), the release notes can link to the other components release notes (or copy-pasted from those repos).

Ultimately it will be the responsibility of the Release Manager to update these notes, but good PR titles could go a long way here.

Here are a couple screenshots of how to generate it, and some examples of what that looks like.

Past Release Notes Guide

Good release notes should assuage fears about changes to things they like, detail what's changed since last time, provide motivation to update, give only those technical detail so folks can make a mental picture of what the effort's going to be. They should be grouped so people can gravitate to the parts that are relevant to them, such as "new features", "bug fixes", "security updatess", etc.

On top of it all, they: should be a joy to read: sufficiently engaging to keep the interest, brief enough to get people through them all, and a hint of playfulness to make the entire ordeal seem not so bad.

"Playful has no place in software."

Really? If that were the case, we wouldn't have the Google Doodle!

This doesn't mean every bullet item in the release notes has to be a joke. But having a little humor in at least one of them can help make the medicine go down.

Because of all this, I don't see a good way to automate it. I'd have a good technical writer look at the changelog for a release and turn that into a decent set of release notes.

Release Note Guidelines

Summary

provide some high level summary of what is included in this release in 1-2 sentences

Improvements

  • bulleted list of improvements in user-centric language

Bug Fixes

  • bulleted list of bug fixes that are applicable to the user (not internal fixes they probably don't care about)

Example Release Notes 1

Leaning towards something like Release Notes from 1Password on MacOS, but without the need to trace to exact tickets:

Today's release brings a number of improvements to file attachments for 1Password accounts. We've also made a number of improvements to browser integration, making sure 1Password is filling fields as deftly as possible.

Improvements

  • Improved the file attachment interface so that a newly added item shows up immediately and displays progress uploading the file.
  • Attachments now maintain a consistent order between view mode and edit mode.
  • Attachments are now included during export.
  • Improved iCloud export for one-time passwords so that we export a proper otpauth URL when we only have a raw secret value in 1Password.
  • Added a dismiss button to the migration offer and a way to bring it back via Help menu.

Bug Fixes

  • Fixed an issue that caused detached windows to errantly claim to be focused all the time.
  • Fixed an issue that prevented the share item sheet from being presented on detached windows.
  • Fixes a possible crash on launch relating to periodic downloads.
  • Fixed a crash that could occur when running in an unregistered state.