Adopting Changesets for release and changelog automation

Photo by Austin Chan on Unsplash When working on Open Source Software (OSS), documentation is a crucial part of the project. It helps to ease adoption by providing in-depth descriptions on how to get started, how to use advanced functionalities, to communicate best practices with examples, and so on. However, documentation does not end with an initial […]

Photo by Austin Chan on Unsplash

When working on Open Source Software (OSS), documentation is a crucial part of the project. It helps to ease adoption by providing in-depth descriptions on how to get started, how to use advanced functionalities, to communicate best practices with examples, and so on.

However, documentation does not end with an initial release. It continuously evolves during the life-cycle of the project. New versions can contain new features, bug fixes, improvements, or even breaking changes. All of that needs to be documented and communicated properly.

How can we communicate changes to the users?

Traditionally, people expect to find this information in a file called CHANGELOG.md, or in GitHub Releases.

A release can include different things: links to commits or Pull Requests related to the new version, contextual information and code examples, emojis, and so on. At the end of the day, it’s just Markdown and it's up to the maintainers of the project to provide necessary and useful information.

Certain parts of the release notes often require manual content and review, while other parts can be automated.

Automating all the things

Ideally, the release notes for your project should have some kind of consistency. This is where tools and automation can come in to help.

This becomes very useful particularly in large projects, or in monorepositories (or monorepos for short) with a lot of packages.

For instance, the release process including generating release notes can be automated and seamlessly integrated into your Continuous Integration (CI) system. Some popular examples include Semantic Releases, Lerna with Lerna Changelog, and many other community projects.

These automation tools can provide by default a lot of context about the release, such as references to Pull Requests, commit messages, list of contributors, etc.

Release Notes in a Monorepos

At commercetools, we have a bunch of open source monorepositories and as such, we needed a way to make the process simple and effective for all the contributors.

So far we’ve been using Lerna and Lerna Changelog. The tools work great and they are very helpful to manage and release multiple packages within the same repository.

However, certain steps have to be taken during the release process to ensure that the release notes are properly documented.

For instance, merged Pull Requests that should be included in the release notes must have a label assigned to them. This allows Lerna Changelog to reference the Pull Request and group it appropriately in the generated release notes.

After running the changelog command, we need to manually add the output to the CHANGELOG.md file and in GitHub Releases. We don’t want to have this step fully automated, as sometimes we need to provide more contextual information — which requires manual writing.

While it’s very helpful and nice, the publication of release notes isn’t fully automated and relies on the user knowing what to do.

This could be a bit of an issue for contributors who aren’t very familiar with the release process or are afraid to mess things up, so they end up getting discouraged from doing it.

Using Changesets

Recently I’ve been looking into another interesting project called Changesets. It’s described as:

A way to manage your versioning and changelogs with a focus on monorepos

It takes a bit of a different approach and it’s designed to work within a monorepository, which is very important for us.

There is a nice documentation page about the motivation and design principles behind the project. I recommend to go check it out.

What I like about the project is that you document the changes as you develop them. Those changes then dictate which packages will eventually be released. Additionally, each package gets its own CHANGELOG.md file, which is also nice and helpful when searching for changes of a specific package.

Automation Bots

Using the changesets command-line interface (CLI) on its own is still not super useful. However, combine it with the Changesets GitHub App and the Changesets GitHub Action, and suddenly you have a powerful killer feature.

The new workflow roughly looks like this:

  • You open a Pull Request and include a changeset file with a proper documentation of the changes and the desired semantic version bump (major, minor, patch).
  • Merging the Pull Request does not trigger any release, instead a new Pull Request named Version Packages is created by the Changeset GitHub Action and includes the release plan. The release plan bumps the versions of all packages and dependent packages affected by the changeset files present in the repository, as well as the updated CHANGELOG.md files in each package.
  • When it’s time to trigger a release, you simply merge the Version Packages Pull Request. The Changesets GitHub Action takes care of doing the actual release, by publishing the packages to NPM, creating the git tags and the GitHub Release notes.

The steps mentioned above assume that you have installed the Changesets GitHub App and configured the Changesets GitHub Action.

Conclusion

The Changesets project gets many points right, compared to how we previously worked with versioning and release notes, and it fits perfectly with the monorepository workflow that we have. It also simplifies the process of releasing and documenting version changes significantly, making that much more accessible to contributors of our projects.

We can only recommend to try it out!


Adopting Changesets for release and changelog automation was originally published in commercetools tech on Medium, where people are continuing the conversation by highlighting and responding to this story.

Source: Commercetools