Develop consistent method for capturing release notes across all PDS repositories #20
Description
💡 Description
Looking to standardize some common way for we, the PDS, should capture release notes for releases of software components.
Right now, we use the CHANGELOG as our primary view of what has changed, but that tends to be too technical/granular for the everyday user. We need some simple, manually curated release notes to describe in more user-centered terms what is new, what is fixed, and any backwards incompatibilities. Let's use this issue to throw out some ideas, and we can talk at the 2/3/22 breakout. What I am looking for:
(1) common mechanism for capturing these notes (some file in the repo, a page in the online docs, etc.)
(2) what do the release notes actually look like? - a consistent format for how we present this to this to the user
Let's start the discussion on (1), and then we can switchover to (2) once we have some ideas. If folks know of good best practices out there for this, that would be ideal so we are not re-inventing the wheel.
Some ideas to get us started:
a. Add a RELEASE_NOTES.md at the top of every repo that we link to from our documentation.
b. Use Github discussion threads - I did this for a validate release to just see how it might work
c. Include the notes in the actual tagged release on Github - You can actually put a custom description on these release pages
(a) seems like the easiest solution with the least amount of effort. we would just need to add this to our procedures for our "release engineer". (b) or (c) would be nice, but would require more manual clicking through the repos and/or update to roundup