The Problem

Several months ago, I set out to solve a pain point I was running into at work — manually writing release notes by copy and pasting entries from Merge Request descriptions. I couldn't find an existing tool that quite worked the way we wanted it to work. We didn't necessarily want to use git commit messages as our changelog entries, which eliminates a lot of the other changelog tools out there.

We wanted to have explicit control over the changelog entries, and we wanted our developers to be intentional and thoughtful about the messages they add to the changelog. This manifested itself in the following workflow, supported by a set of bash scripts I set up:

• Each Merge Request contains a changelog entry in a single, self-contained markdown file within a changelogs/ directory (a file can contain multiple lines, each line being an individual changelog entry)
  • These changelogs are strictly validated against a format pattern
  • This is enforced in a step of the CI build
• When tagging a release, we first run a script which:
  • Iterates through all files under changelogs/
  • Copies each entry within each file into the global CHANGELOG.md file
  • Deletes all individual entry files under changelogs/

After a few weeks of testing and tweaking the scripts which helped us automate this workflow, it turned out it worked really, really well for us.

These scripts, however, lived directly in one repository, so the release notes process for our other projects remained a manual process. This prompted an evolution of the tooling such that it could be shared between projects.

The Result

Enter Yaclt, or: Yet Another ChangeLog Tool. Yaclt is the next evolution of this set of bash scripts; it's a proper command line tool, written in TypeScript, and highly configurable to meet the specific needs of a project, or even a specific developer.

Each command is configurable with many options, and any option can also be specified in a configuration file. The configuration file supports yaml, JSON, or Javascript format; if you're using a Javascript configuration file, any option can be a function which returns the option value. This can be useful for things like computing the next release number from git history, or using a package.json version as the release number.

The tool also has some built-in features like parsing issue numbers from git branch names, given a format to match against, using the first line of your most recent commit message as the changelog message, opening generated changelogs in $EDITOR, and more.

Generating and validating changelog entries is super simple:

And so is collecting the entries into the global CHANGELOG.md to prepare for a release:

This project is still a work in progress, and there are some great ideas for enhancements in the backlog, but it should be usable for your basic changelog workflow. Please open an issue if you run into any problems or pain points (or even better, submit a Pull Request)!

Stars on the repository are greatly appreciated!