For years, my team and I manually updated the changelog for our 250+ packages. Recently, we’ve improved how we go about this.
In this blog post, I’d like to tell you all about it.
What is a changelog?
In our packages, a changelog is a simple markdown file where we note all changes to our packages in chronologic order. We do this to make it easy for the users, contributors and ourselves to see when a particular change has been made.
Here’s an example changelog from the spatie/ray package. To know more about changelogs in general, head over to the keep a changelog website.
Auto generating release notes
Previously, we manually edited the changelog file whenever we did a new release of a package. As the description, we used the PR titles that were merged in a particular release of It’s not a lengthy task, but because of the sheer amount of packages and release our team does, it amounts to quite some time in total.
Recently, GitHub made some changes to the UI when creating a new release. A new button, “Auto-generate release notes”, was added. When pressing this button, a text snippet containing all changes is generated. This snippet also mentions all (new) contributors, which is very nice. Finally, a link to a full diff between the new a previous release is added.
Here’s how those release notes look like when the release is actually created.
Looks good, right?
Automatically updating the changelog
Now that we know how to generate release notes automatically, let’s look at how we can automatically add these notes to the changelog.md in the repo.
A while ago, Stefan Zweifel released a very cool changelog-updater-action to automatically copy the release notes to changelog.md whenever a new release is tagged. A very cool thing to note is that this action is powered under the hood by a Laravel application.
We’re now using this action in most of our repos. Here’s the workflow that was added to the spatie/ray repo. It’ll run whenever a new release is created.
It will add a commit like this one to update the changelog.
.
Very nice!
In closing
Stefan’s changelog-updater-action will save my team and me quite some time.
Right now, GitHub’s release notes can only be generated from their website. I hope that their CLI will also be updated in the future to also generate these excellent release notes right from the terminal.
.
Also check out Stefan’s blog post on his updater action, which mention a few other configuration options.
If you want to know more about creating quality packages and how we at Spatie handle this, check out Laravel Package Training premium video course, which was recently updated for Laravel 8 and PHP 8.
