RELEASE NOTES

You've studied the Git/hacks and built a ton of features, fixes, and updates to your codebase in a sprint worthy of Usain Bolt. Now it's time to create some release notes - which in the tradition of open source is stored in the RELEASE_NOTES file of your project.

Since your team follows the best practices of writing good commit comments and also creating appropriate branches and pull requests, then it's a simple matter of letting git tell you what's in the release. Of course you can amend or add to it as needed.

1. First, study git/log for how to use the log command.
2. Optionally, if you are adopting a formal process for the first time and do not want to go all the way back in time to publish your release notes, you might need to figure out the say the last parent branch where you want to 'start' your notes. See Git/hacks
3. Iterate on git log commands to find the one that works for you. E.g. git log --stat or git log --pretty between the prior branch/tag and HEAD (or current release tag)

In the final analysis, use --no-merges
to show the whole commit history, but skip any merge commits so that the Release Notes are not cluttered with workflow items.

git log --no-merges --format="%(decorate:prefix=,suffix=%n,tag=%n## Meza ,separator= )* %h (%as) %an: %s %b" 39.5.0...HEAD > RELEASE_NOTES-UPDATE.md generates a pretty good update to the RELEASE_NOTES since v39.5.0 which is then manually reviewed and edited to clarify commit messages; add links etc.

Current Method

Using a combination of git log to produce the Notes

plus sed to convert commit SHAs to GitHub links

and convert Issue references to GitHub Issue links, we get a pretty good RELEASE NOTES for any given range of commits.

By naming the file .md, and creating the links in markdown format, we can see the links as clickable in both GitHub and in VSCode with Markdown preview, bringing interactivity to the notes where developers want to drill down into details.

Bash example 'one-liner'

export START=43.25.11; \
export END=43.29.1; \
git log --no-merges --name-status --format="%(decorate:prefix=,suffix=%n,tag=%n## Meza ,separator= )* %h (%as) %an: %s %b" $START..$END \
| sed -E 's/\* ([0-9a-f]{8})/\* [\1](https:\/\/github.com\/freephile\/meza\/commit\/\1)/g'  \
| sed -E 's/Issue # ?([0-9]{1,4})/Issue [#\1](https:\/\/github.com\/freephile\/meza\/issues\/\1)/Ig' \
> RELEASE_NOTES-$END.md

We formalized it and turned it into a script: generate-release-notes.sh

See Meza RELEASE_NOTES-43.29.1.md as an example of the output.

In MediaWiki

In the MediaWiki project, Release Notes are a hybrid mix of "CHANGELOG" (what I would call a pure version control / issue tracker list) plus "Product" notes about new features, deprecations and the important highlights of the release. For each release, there is a file produced with the naming convention of RELEASE-NOTES-1.NN with all prior contents stored chronologically in the HISTORY file.

See on-wiki RELEASE NOTES for version 1.43 and the RELEASE-NOTES-1.43 file in the repository.

See Also: https://www.mediawiki.org/wiki/Release_notes/data