# Advice on how to handle CHANGELOG?

**URL:** <https://discourse.laminas.dev/t/advice-on-how-to-handle-changelog/1562>\
**Category:** Contributors\
**Created:** [April 27, 2020, 8:45am UTC](https://discourse.laminas.dev/t/advice-on-how-to-handle-changelog/1562 "2020-04-27T08:45:49Z")\
**Posts on this page:** 6\
**Page:** 1

<div class="post-metadata">

**Author:** ![PowerKiKi](https://yyz2.discourse-cdn.com/flex032/user_avatar/discourse.laminas.dev/powerkiki/32/48_2.png) [@PowerKiKi](https://discourse.laminas.dev/u/PowerKiKi)\
**Post date:** [April 27, 2020, 8:45am UTC](https://discourse.laminas.dev/t/advice-on-how-to-handle-changelog/1562/1 "2020-04-27T08:45:49Z")

</div>

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](https://github.com/angular/angular/blob/master/CHANGELOG.md) ? 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 ?**

---

<div class="post-metadata">

**Author:** ![ocramius](https://yyz2.discourse-cdn.com/flex032/user_avatar/discourse.laminas.dev/ocramius/32/23_2.png) [@ocramius](https://discourse.laminas.dev/u/ocramius)\
**Post date:** [April 27, 2020, 12:48pm UTC](https://discourse.laminas.dev/t/advice-on-how-to-handle-changelog/1562/2 "2020-04-27T12:48:33Z")

</div>

I think you are looking for [https://github.com/zendframework/maintainers](https://github.com/zendframework/maintainers)

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

---

<div class="post-metadata">

**Author:** ![boesing](https://yyz2.discourse-cdn.com/flex032/user_avatar/discourse.laminas.dev/boesing/32/832_2.png) [@boesing](https://discourse.laminas.dev/u/boesing)\
**Post date:** [April 28, 2020, 5:55pm UTC](https://discourse.laminas.dev/t/advice-on-how-to-handle-changelog/1562/3 "2020-04-28T17:55:18Z")

</div>

Its not ported yet.

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

The CHANGELOG.md is following the (unofficial) [keep-a-changelog](https://keepachangelog.com/de/1.0.0/) 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.

---

<div class="post-metadata">

**Author:** ![matthew](https://yyz2.discourse-cdn.com/flex032/user_avatar/discourse.laminas.dev/matthew/32/14_2.png) [@matthew](https://discourse.laminas.dev/u/matthew)\
**Post date:** [April 28, 2020, 7:40pm UTC](https://discourse.laminas.dev/t/advice-on-how-to-handle-changelog/1562/4 "2020-04-28T19:40:25Z")

</div>

As @boesing notes, we use the [Keep A Changelog](https://keepachangelog.com) format for our changelogs, and I wrote a [CLI tool](https://github.com/phly/keep-a-changelot) 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](https://github.com/weierophinney/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 —

> [@ocramius](#):
>
> I think you are looking for [GitHub - zendframework/maintainers: Contributors and maintainers information for Zend Framework.](https://github.com/zendframework/maintainers)
> 
> Can’t find it under laminas right now: maybe not ported or renamed differently?

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.

---

<div class="post-metadata">

**Author:** ![PowerKiKi](https://yyz2.discourse-cdn.com/flex032/user_avatar/discourse.laminas.dev/powerkiki/32/48_2.png) [@PowerKiKi](https://discourse.laminas.dev/u/PowerKiKi)\
**Post date:** [May 13, 2020, 1:22pm UTC](https://discourse.laminas.dev/t/advice-on-how-to-handle-changelog/1562/5 "2020-05-13T13:22:36Z")

</div>

Thank you all for your valuable inputs 🎉

[https://github.com/phly/keep-a-changelog](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](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](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…

---

<div class="post-metadata">

**Author:** ![matthew](https://yyz2.discourse-cdn.com/flex032/user_avatar/discourse.laminas.dev/matthew/32/14_2.png) [@matthew](https://discourse.laminas.dev/u/matthew)\
**Post date:** [May 14, 2020, 4:44pm UTC](https://discourse.laminas.dev/t/advice-on-how-to-handle-changelog/1562/6 "2020-05-14T16:44:21Z")

</div>

> [@PowerKiKi](#):
>
> However it still require to manually edit the changelog which I would prefer to avoid (unfortunately for the end-users).

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

```bash
$ 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.