DEV Community

Cover image for My Favorite Way to Do a Changelog
Matt Haggard
Matt Haggard

Posted on

My Favorite Way to Do a Changelog

If you publish code for others to use, it's very beneficial to also publish a Changelog. I won't rehash what's already written in Keep a Changelog. But I will share my conflict-free method for maintaining such a log.

The Method

Let's assume your changelog is in Instead of accumulating unreleased changes at the top of that file in an "Unreleased" section, put each entry in a separate file:

  1. Create a ./changes/ directory
  2. For any change worth noting, commit a new file in ./changes named For example: or
  3. When it's time to make a new release, gather up the files and add them to the top of, grouped and labeled by change type.
  4. Then delete the files.

By using this method you don't have to fix conflicts in, either when merging or when backing out a change.

Other Options

Instead of using markdown snippets, you could use a more structured format if you want more structure (e.g. TOML, YAML, XML, JSON, etc...). I haven't needed this yet.

Example Script

It's fairly simple to automate this in your project's language. Here's an example of doing this with Nim.

import os
import strutils
import strformat
import times
import tables

if paramCount() < 1:
  let prog = getAppFilename()
  echo &"usage: {prog} NEWVERSION"

let today = now().format("yyyy-MM-dd")
let newversion = &"[{paramStr(1)}] - {today}"
let changedir = "changes"

# Option: You could make the script look in and
# guess the next version based on the presence of fixes, breaking
# changes, or new features.

var changes = initOrderedTable[string, seq[string]]()
changes["breaking"] = @[]
changes["fix"] = @[]
changes["new"] = @[]
changes["doc"] = @[]
changes["misc"] = @[]

for file in changedir.walkDir:
  let changetype ="-")[0]
  if changes.hasKey(changetype):
    var prefix = ""
    case changetype
    of "breaking": prefix = "**BREAKING CHANGE:** "
    of "fix": prefix = "**FIX:** "
    of "new": prefix = "**NEW:** "
    changes[changetype].add("- " & prefix & file.path.readFile.strip)
    changes["misc"].add("- " & file.path.readFile.strip)

# Option: You could make this handle multi-line entries

echo &"## {newversion}"
echo ""
for entries in changes.values:
  for line in entries:
    echo line

# Option: You could make this update in place

What the sample change snippets look like:

$ grep "" changes/*
changes/ broke a thing
changes/ documentation
changes/ thing
changes/ did something

Running it:

$ nim c -r changelog.nim 1.2.0
## [1.2.0] - 2020-09-15

- **BREAKING CHANGE:** I broke a thing
- **FIX:** Another thing
- **FIX:** I did something
- Fixed documentation

Top comments (0)