Updated with new run
command.
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 looked like this?
Or this one:
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.
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?
To find an answer:
@deprecated
, what is the replacement?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
?
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.
CHANGELOG.md
composer require symplify/changelog-linker --dev
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)
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!