DEV Community

Mat Jones
Mat Jones

Posted on • Originally published at mjones.network

Introducing Yaclt (Yet Another ChangeLog Tool)

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

yaclt-logo-cropped

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!

GitHub logo mrjones2014 / yaclt

Yet Another Change Log Tool

Build NPM Publish Discord Server

yaclt logo

What is yaclt? It's Yet Another ChangeLog Tool.

yaclt is a file-based changelog generator. The idea is basically the following:

  • For each pull request/merge request, include a changelog file generated by this tool -- it gets stored in source control until the next release
  • To prepare a release, use the prepare-release command, which will
    • Gather all the individual changelog entries into a global CHANGELOG.md (or whatever file you've specified)
    • Delete all the individual changelog files

The changelog entry format and the global changelog file template are both Handlebars templates, and you can use the extra helpers from handlebars-helpers.

Help for each command can be found in COMMANDS.md or by running the command with the --help argument.

Dependencies

yaclt requires that git exists on your $PATH and that node 12+ is installed.

Configuration

All command line flags and arguments can be specified in…

Top comments (0)