Is Your CHANGELOG Useful or Just Boring Plain Text? And How to Fix That
What is new?
Updated with new
This post is written in Markdown. Would you read it if it looked like this?
Moreover now, when Vitek showed me awesome tool called Tomono, that can merge git history from multiple repositories...
Or this one:
What is Sad about..
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.
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
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.
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
composer require symplify/changelog-linker --dev
2. Run it
It will complete links to:
PRs and issues
[#1](https://github.com/symplify/symplify/pull/1) - fix everything
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
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.
Happy lazy linking!