NEILB's Blog

When you make changes to your dist, please note all of them in the Changes file. It may seem like overkill, and a burden, but once you get into the habit it will become just part of your way of working. And you may save time for others.

An example

I was just looking into a bug reported on a dist; let's call it FOO. This immediately looked like another dist — let's call it BAR — wasn't reporting its dependency on FOO. I went and looked at the latest release of BAR, and its metadata dist lists FOO.

The next place to look was BAR's Changes file. No mention of a missing dependency on FOO. So there was nothing for it but to go through the previous releases of BAR on BackPAN. Sure enough, I found that the previous release was dependent on FOO but hadn't declared that. Fortunately I didn't have to trawl back through more releases.

Small atomic changes

If you've got a number of changes to make in your dist, make them independently and atomically. For each change:

• make the change
• add / change a test, if appropriate
• update the doc, if appropriate
• add a line to the Changes file
• make sure all tests (still) pass
• commit to your source control, with a good commit message.

If you're using Dist::Zilla, you could even use the ChangelogFromGit plugin to auto generate your Changes file from those good commit messages.

People tracking down failed builds will thank you if you record every change in your Changes file.

Bonus tip

If you're using git, it may be helpful to know the --amend switch. If you're like me, you might occasionally forget to update the Changes file, or one of the above steps, and realise it after you've commited. If you realise that you've forgotten the Changes update, you'd edit that file then run:

git commit --amend Changes

This includes the change in the previous commit.

I only discovered this relatively recently, but I'm sure glad I did!