Oh Dear is the all-in-one monitoring tool for your entire website. We monitor uptime, SSL certificates, broken links, scheduled tasks and more. You'll get a notifications for us when something's wrong. All that paired with a developer friendly API and kick-ass documentation. O, and you'll also be able to create a public status page under a minute. Start monitoring using our free trial now.

Our improved changelog workflow for packages

Original – by Freek Van der Herten – 3 minute read

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.

Stay up to date with all things Laravel, PHP, and JavaScript.

You can follow me on these platforms:

On all these platforms, regularly share programming tips, and what I myself have learned in ongoing projects.

Every month I send out a newsletter containing lots of interesting stuff for the modern PHP developer.

Expect quick tips & tricks, interesting tutorials, opinions and packages. Because I work with Laravel every day there is an emphasis on that framework.

Rest assured that I will only use your email address to send you the newsletter and will not use it for any other purposes.


What are your thoughts on "Our improved changelog workflow for packages"?

Comments powered by Laravel Comments
Want to join the conversation? Log in or create an account to post a comment.