As an open-source maintainer, I have a severe obsession for informative release notes and I cringe every time I see release notes with the dreadful "Bug fixes and minor improvements" line in it. I like to write my release notes as accurately as possible which is tedious by hand. I decided to use scripting power to ease it.
The script I made uses the Friendly Interactive Shell (you should too) but it's trivial to replicate the same functionality in Bash, ZSH or even include it as a Git alias.
Installation and Usage
You can find the script as a gist and place it within your Fish functions. Here I'm using my Python library pwnedapi for example.
Bash 1curl -sSL https://gist.githubusercontent.com/nikoheikkila/96f734a5dffa7a9e6e32c33e8b2c7ddc/raw/3b98f241e203631915729d165ecf6e767bbff7ca/changes.fish -o ~/.config/fish/functions/changes.fish 2 3changes v1.0.0
Markdown 1## `v1.0.0` 2 3Write your release notes on this line. 4 5- docs: add a security policy (_Niko Heikkilä_) (d02e70a) 6- fix(security): upgrade Python packages (_Niko Heikkilä_) (bbb0861) 7- fix(tests): replace parameter message with matches in pytest.raises (_Niko Heikkilä_) (9161cf9) 8- release: 1.0.1 (_Niko Heikkilä_) (f9cdd53)
The script takes only one argument which is the commit we compare our state to. It's fast, includes all the necessary information, and fully supports Markdown. What more could I ask?
The Recipe
Naturally, you shouldn't blindly trust scripts downloaded from the Internet so let's go over what the script does. The full script can be seen below.
Bash 1function changes -d "Generate a Markdown changelog from conventional commits" -a target 2 3 # Use fallback variables if no arguments were given. 4 if test (count $argv) -eq 0 5 set target master 6 end 7 8 # Include commit message, author name, and the short hash in parentheses. 9 set -l log_format "%s (_%aN_) (%h)" 10 11 # Compare against HEAD (the latest commit). 12 set -l source "HEAD" 13 14 # Filter to commits that pass the conventional commit format. 15 # See: https://www.conventionalcommits.org/ 16 set -l commit_filter "^[a-z]+(\([a-z]+\))?:\s.+" 17 18 # Prefix each line with '- ' to render a Markdown list. 19 set -l prefix '{print "- " $0}' 20 21 # Write changelog header 22 echo -e "## `$target`\n\n" 23 echo -e "Write your release notes on this line.\n\n" 24 25 # Fill and sort the actual changelog 26 git log --oneline --pretty=format:$log_format $source...$target \ 27 | grep -E "$commit_filter" \ 28 | sort -k1 \ 29 | awk "$prefix" 30 31end
The core of this tool is, naturally, git-log which is a powerful tool for finding out what's going on in your projects. Here we use it to print a compact one-liner log formatting each message with a custom pattern where:
%sis the commit title%aNis the commit author's name respecting the.mailmapfile if there's one%his the commit hash in a short format
The reason we include commit hash to our changelog is that GitHub and Gitlab will automatically link these hashes to their respective commit pages for viewing the entire diff. It's an extremely handy way to verify that a commit implements what it states.
Git can produce a log from a range of commits. Since branches and tags are pointers to a single commit we can specify those here. We compare from HEAD or the current state of clone to the given pointer to produce a list of recent changes.
Next, we pipe the log output to grep tool passing a regular expression filter which requires the commit title to pass the Conventional Commits notation. You can modify this filter if you want but I like to keep it as is to enforce my team to use a shared commit template. If you are not familiar with Conventional Commits I highly recommend you read the aforementioned link and adopt it to your workflow.
Next, we want to group those commits so that each commit title prefix whether it's feat, fix, docs, or something else will stick together and sort is the solution for that. Finally, to fully leverage Markdown syntax we prefix each commit line with a dash using awk.
Bonus: Export in Any Format
Now that we have the changelog in Markdown we can put it anywhere and in any format we want thanks to Pandoc. To convert the changelog to eg. HTML pipe it like so (replace html to try out other formats):
Bash 1changes v1.0.0 | pandoc -f markdown -t html
HTML 1<h2 id="v1.0.0"><code>v1.0.0</code></h2> 2 3<p>Write your release notes on this line.</p> 4 5<ul> 6 <li>docs: add a security policy (<em>Niko Heikkilä</em>) (d02e70a)</li> 7 <li> 8 fix(security): upgrade Python packages (<em>Niko Heikkilä</em>) 9 (bbb0861) 10 </li> 11 <li> 12 fix(tests): replace parameter message with matches in pytest.raises (<em 13 >Niko Heikkilä</em 14 >) (9161cf9) 15 </li> 16 <li>release: 1.0.1 (<em>Niko Heikkilä</em>) (f9cdd53)</li> 17</ul>
Next time you need to craft a new release for your project, try spicing it up with a great changelog. ✨🍰