Advice on how to handle CHANGELOG?

This is not only about Laminas but rather it’s about general workflow for open-source projects. And I think past and present Zend and Laminas contributors might have valuable insights to share.

As one of the maintainer of PhpSpreadsheet project, I’ve been struggling with changelogs. More specifically on how to handle changelogs when merging a PR. As a user I love reading a well crafted changelog, but as a maintainer it can be very time consuming for something that might seems (technically) trivial.

For PhpSpreadsheet we’ve been asking contributors to edit the changelog themselves as part of the PR. However it does not work that well for various reasons. Mostly because either contributors don’t take the time to do it at all, or because maintainers take too long to merge, and the the CHANGELOG will conflict on merge. Or worse it will not conflict, but be incorrectly merged into an already released version.

So I end up spending a lot of time adding or merging changelogs, and I was wondering how others do it ?

I believe Zend used to have an automated tool at some point, to extract changelogs from the commits. But it seems to have been abandoned for Laminas ? (or maybe way before that ?)

How can Laminas handle changelog in an effective manner and not do a lot of manual work ?

In your experience wouldn’t an automated tool be more efficient ? But then that would probably add constraint about commit message format ?

Did any of you experience with something like what Angular does ? The result is pretty cool, though it brings strict commit message rules. Would you be aware of something similar in PHP ecosystem ?

In the way we do it for PhpSpreadsheet, I see the following advantages:

  • changelog entry is in the same commit as the actual change, so easy to navigate git history
  • commit can be technical while changelog is kept a little bit more user-friendly

But the obvious downside is that I spent a lot of time handling those and not coding something useful…

tl;dr what is your experience and recommendation to write/generate changelogs ?

I think you are looking for https://github.com/zendframework/maintainers

Can’t find it under laminas right now: maybe not ported or renamed differently?

Its not ported yet.

Most, if not all, of us use https://github.com/phly/keep-a-changelog as per suggestion of @matthew

The CHANGELOG.md is following the (unofficial) keep-a-changelog format.

The library can therefore be used for any project as long as the CHANGELOG.md format is correct. It can be configured for github, gitlab, e.g.

1 Like

As @boesing notes, we use the Keep A Changelog format for our changelogs, and I wrote a CLI tool to make it easy for us to:

  • Add entries
  • Set version dates
  • Create tags that contain the current changelog
  • Create releases that contain the current changelog
  • Bump to new versions
  • Remove versions (e.g., removing an empty changelog for a bugfix version never released)

Additionally, it allows you to free-form edit any changelog version.

We encourage users to add a changelog entry as part of their pull request via our PR template. If they do not, as maintainers, we add one during merge.

Why this approach, instead of something like my older tool, changelog_generator? I’ve found that PR subject lines are often too succinct, too technical, or too vague; they don’t give the user reading the changelog a real idea of the impact of the change. Keep A Changelog encourages writing changelogs for human consumption. I find the same is true with commit messages, particularly when we do not squash commits to get rid of “fixes typo” style intermediate commits; they’re too terse for consumption as part of a changelog.

@ocramius

It’s not been ported, and some of the stuff is no longer the same — though the maintainer’s guide is roughly the same as what we do now.

1 Like

Thank you all for your valuable inputs :tada:

https://github.com/phly/keep-a-changelog seems very interesting, especially to create releases on GitHub in an easier way. I’ll definitely give it a try. However it still require to manually edit the changelog which I would prefer to avoid (unfortunately for the end-users).

https://github.com/weierophinney/changelog_generator is of course not a option since it is not maintained anymore. But Tomas Votruba (from RectorPHP) recommended me https://github.com/symplify/changelog-linker. It is able to generate a changelog based on commits while still preserving categories of “added”, “fixed” and “changed”. It seems to be working even without strict rules for writing commit. So it should work out of the box with most PR from any contributors.

I need try in a real-world scenario, but I might end up generating changelog with symplify/changelog-linker, and then creating releases on GitHub with phly/keep-a-changelog.

I have to say though that I really appreciate the quality of changelogs seen in Laminas packages. So this automation is not entirely satisfactory. But I hope the trade off is worth it…

Um… not really? You don’t actually fire up an editor to edit the changelog. Instead you use the CLI. As an example:

$ keep-a-changelog entry:fixed --pr 7 'fixes some issue in the package.'

and it then updates the current changelog version to add an entry in the Fixed section with the information you provide. Yes, this requires you to write the entries — but that’s a good thing. That’s actually the whole point of the Keep-A-Changelog format: to write human readable changelogs. That’s the whole reason you can cite the quality of our changelogs: because we, as humans, curate them for other humans.

My point is: changelogs should require some effort, as you need to distill the changes into something actionable by the reader. Issue and patch titles don’t generally give this information in a useful way. And one thing I’ve realized since using the format is that there is a lot of change that does not need to be messaged to the user: QA changes, updates to documentation, addition of tests, etc. Knowing what new features exist, which bugs were fixed, what’s being deprecated (and what changes to make to avoid deprecated features!) — that stuff is interesting.

1 Like