Is Your CHANGELOG Useful or Just Boring Plain Text? And How to Fix That

2018-01-15

This post is written in Markdown. Would you read it if it looked like this?

Or this one:

What is Sad about..

...Missing References?

Imagine you'll read my post first plain text version. While reading it, you might think:

• What is this monorepo? Isn't that monolith - an antipattern?
• I didn't know Google is using monorepo?
• Is that true name or made-up one?

You could read answer to all those questions if I'd only provide links - but you can't, because there are no links. You'd have to go to comments, ask them, wait for answers... So you'll probably end up closing my blog and never come again.

...Plain Text CHANGELOG.md?

It takes maintainer a lot of effort to keep a changelog, keep it updated, with every version and every new pull-request, refer issues, pull-request, @author references...

"Too many cooks spoil the broth."

No surprise that most CHANGELOG.md files look like this:

## v3.2.0 - 2018-01-18

### Changed

- #560 Added `PhpdocVarWithoutNameFixer` to `docblock.neon` level, thanks to @carusogabriel
- #578 Use `@doesNotPerformAssertions` in tests, thanks to @carusogabriel

Does your CHANGELOG.md look like this too? Is it just dump of pull-requests combined with releases?

Why do we Look to Changelog?

To find an answer:

• What has changed in new version?
• If it was @deprecated, what is the replacement?
• Most often when it broke our code and we're angry: what are the reasons for this change?
• How did it work before?
• Was there some issue?
• Who is that active person behind all pull-requests for this release?

I've asked all these questions when I was investigating bug in packages I used.

Often, release descriptions are not so detailed. In that case it is really helpful to have comparison to previous version, e.g. 3.1 to 3.2.

But all of this requires time. A time that maintainer usually puts to new features or resolving bugs.

When I added CHANGELOG.md to Symplify and moved all notes from Github Releases there, I was in the same situation. Do I create new features or rather play and cuddle with my CHANGELOG.md?

Can't let go? Automate!

I wanted both. Why? Because I was used to Github Released that work like I needed:

## v3.2.0 - 2018-01-18

### Changed

- [#560](https://github.com/symplify/symplify/pull/560) Added `PhpdocVarWithoutNameFixer` to `docblock.yml` level,
   thanks to [@carusogabriel](https://github.com/carusogabriel)
- [#578](https://github.com/symplify/symplify/pull/578) Use `@doesNotPerformAssertions` in tests,
   thanks to [@carusogabriel](https://github.com/carusogabriel)

I've closed myself to coffee house for 3 hours and I've came up with solution!

A Changelog Linker was born.

3 Steps To Add Links To Your CHANGELOG.md

1. Install

composer require symplify/changelog-linker --dev

2. Run it

vendor/bin/changelog-linker run

It will complete links to:

• PRs and issues

  [#1](https://github.com/symplify/symplify/pull/1) - fix everything

• Version Diffs

  # [v2.0.0](https://github.com/symplify/symplify/compare/v1.5.0...v2.0.0)

• Users

  Thanks to [@SpacePossum](https://github.com/SpacePossum)

3. Commit and Push

git add .
git commit -m "CHANGELOG: add links to PRs, issues, version diffs and user names"
git push origin master

That's it!

I'm sorry I didn't follow this rule from PHP Package Checklist and used Github Releases instead. But now I have no more excuses.

I hope you to...

Huge thanks to @olivierlacan for keepachangelog.com! It helped me a lot.

Oh, sorry...

Huge thanks to @olivierlacan for keepachangelog.com!

Happy lazy linking!