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

Do you keep a CHANGELOG? You should! I do, because it's the main story about the open-source package.

And if you do, is it boring plain text or useful rich markdown?

This post is written in Markdown. Would you read it, if it would look like this?


I wrote about monorepo before and - as ShopSyS and Google agrees - it's the best choice for longterm projects, like children or planet projects.

Moreover know, when Vitek showed me awesome tool called Tomono, that can merge git history from multiple repositories...


Or this one:


I wrote about monorepo before and - as ShopSyS and Google agrees - it's the best choice for longterm projects, like children or planet projects.

Moreover know, when Vitek showed me awesome tool called Tomono, that can merge git history from multiple repositories...



Btw, Hypertext Markup Language (HTML) is here since 1993, so we might integrate it in its natural environment. Same for Markdown and not just because it's a markup language.


What is Sad about Missing References?

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

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.

What is Sad about 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:

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.neon` 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.

1. Install

composer require symplify/changelog-linker --dev

2. Run it

vendor/bin/changelog-linker CHANGELOG.md --repository https://github.com/symplify/symplify

Option --repository is used for links to PRs, issues and commits.

It will complete links to:

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!


What do you think?


GitHub RSS @votrubaT Runs on Statie Hosted on GitHub

Like what I write about? Hire me & we can work together