Movatterモバイル変換


[0]ホーム

URL:


Skip to content
DEV Community
Log in Create account

DEV Community

Cover image for Generating Conventional Changelogs
Niko Heikkilä
Niko Heikkilä

Posted on • Originally published atnikoheikkila.fi

     

Generating Conventional Changelogs

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 agist and place it within your Fish functions. Here I'm using my Python librarypwnedapi for example.

curl-sSL https://gist.githubusercontent.com/nikoheikkila/96f734a5dffa7a9e6e32c33e8b2c7ddc/raw/3b98f241e203631915729d165ecf6e767bbff7ca/changes.fish-o ~/.config/fish/functions/changes.fishchanges v1.0.0
Enter fullscreen modeExit fullscreen mode
## `v1.0.0`Write your release notes on this line.- docs: add a security policy (_Niko Heikkilä_) (d02e70a)- fix(security): upgrade Python packages (_Niko Heikkilä_) (bbb0861)- fix(tests): replace parameter message with matches in pytest.raises (_Niko Heikkilä_) (9161cf9)- release: 1.0.1 (_Niko Heikkilä_) (f9cdd53)
Enter fullscreen modeExit fullscreen mode

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.

functionchanges-d"Generate a Markdown changelog from conventional commits"-a target# Use fallback variables if no arguments were given.iftest(count$argv)-eq 0settarget master    end# Include commit message, author name, and the short hash in parentheses.set-l log_format"%s (_%aN_) (%h)"# Compare against HEAD (the latest commit).set-lsource"HEAD"# Filter to commits that pass the conventional commit format.# See: https://www.conventionalcommits.org/set-l commit_filter"^[a-z]+(\([a-z]+\))?:\s.+"# Prefix each line with '- ' to render a Markdown list.set-l prefix'{print "- " $0}'# Write changelog headerecho-e"##`$target`\n\n"echo-e"Write your release notes on this line.\n\n"# Fill and sort the actual changelog    git log--oneline--pretty=format:$log_format$source...$target\    |grep-E"$commit_filter"\    |sort-k1\    |awk"$prefix"end
Enter fullscreen modeExit fullscreen mode

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:

  • %s is the commit title
  • %aN is the commit author's name respecting the.mailmap file if there's one
  • %h is 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 just pointers to a single commit we can specify those here. We compare fromHEAD or the current state of clone to the given pointer to produce a list of recent changes.

Next, we pipe the log output togrep tool passing a regular expression filter which requires the commit title to pass theConventional 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'sfeat,fix,docs, or something else will stick together andsort is the solution for that. Finally, to fully leverage Markdown syntax we prefix each commit line with a dash usingawk.

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 toPandoc. To convert the changelog to eg. HTML pipe it like so (replacehtml to try out other formats):

changes v1.0.0 | pandoc-f markdown-t html
Enter fullscreen modeExit fullscreen mode
<h2id="v1.0.0"><code>v1.0.0</code></h2><p>Write your release notes on this line.</p><ul><li>docs: add a security policy (<em>Niko Heikkilä</em>) (d02e70a)</li><li>fix(security): upgrade Python packages (<em>Niko Heikkilä</em>) (bbb0861)</li><li>fix(tests): replace parameter message with matches in pytest.raises (<em>Niko Heikkilä</em>) (9161cf9)</li><li>release: 1.0.1 (<em>Niko Heikkilä</em>) (f9cdd53)</li></ul>
Enter fullscreen modeExit fullscreen mode

Next time you need to craft a new release for your project, try spicing it up with a great changelog. ✨🍰

Top comments(1)

Subscribe
pic
Create template

Templates let you quickly answer FAQs or store snippets for re-use.

Dismiss
CollapseExpand
 
nikoheikkila profile image
Niko Heikkilä
Software craftsman with a strong passion for open source software and continuous improvement.
  • Email
  • Location
    Tampere, Finland
  • Education
    Software Engineer / Self-Taught
  • Work
    Software Engineer at Futurice
  • Joined

Yes, there are a lot of cool tools for those who wish to do more than just generate changelogs. I'll be sure to givestandard-version a try in the future.

Are you sure you want to hide this comment? It will become hidden in your post, but will still be visible via the comment'spermalink.

For further actions, you may consider blocking this person and/orreporting abuse

Software craftsman with a strong passion for open source software and continuous improvement.
  • Location
    Tampere, Finland
  • Education
    Software Engineer / Self-Taught
  • Work
    Software Engineer at Futurice
  • Joined

More fromNiko Heikkilä

DEV Community

We're a place where coders share, stay up-to-date and grow their careers.

Log in Create account

[8]ページ先頭

©2009-2025 Movatter.jp