Reformatted Changes file as per CPAN::Changes::Spec

[neilb]

Hi David,

I'll save you from my usual speil. I tried to make the format look like the most recent block, which I assume is your preferred style.

Neil

[neilb]

Oh bugger, I hadn't noticed this was a Toolchain gang dist. Now you're going to tell me to apply it myself ...

[dolmen]

The diff is unreadable :(. No way to check that you didn't break the changelog.

[dolmen]

Fixing the changelog step by step with a diff (commit) for each release would be easier to check.

[neilb]

Does this help:

http://neilb.org/file-temp-diff.html

[dagolden]

I think my "preferred style" as you describe it was just trying not to deviate too terribly from the past. I like the improvements, so +1 to apply from me.

[neilb]

Thanks @dolmen: in doing that diff I spotted a typo I'd introduced in a version number, and one thing not lining up.

[shadowcat-mst]

On Thu, Sep 26, 2013 at 02:57:38PM -0700, Neil Bowers wrote:

Hi David,

I'll save you from my usual speil. I tried to make the format look like the most recent block, which I assume is your preferred style.

Note that there's currently a pull request open to make metacpan parse changes
files in general, and I'm discussing relaxing the spec with the author.

If the reformatting produces genuinely improved readability, great. If it's
a knee jerk reaction to metacpan's broken parsing approach, please ask yourself
if it -also- produces genuinely improved readability.

Also note that reformatting historical changes will break every single sanely
written generic changelog viewer in the world (since they operate by diff). Is
this enough of an improvement to justify that?

Matt S Trout - Shadowcat Systems - Perl consulting with a commit bit and a clue

http://shadowcat.co.uk/blog/matt-s-trout/ http://twitter.com/shadowcat_mst/

Email me now on mst (at) shadowcat.co.uk and let's chat about how our CPAN
commercial support, training and consultancy packages could help your team.

[andk]

shadowcat-mst [email protected] writes:

Note that there's currently a pull request open to make metacpan parse changes
files in general, and I'm discussing relaxing the spec with the
author.

Is this discussion conducted in public?

[...]

Also note that reformatting historical changes will break every single sanely
written generic changelog viewer in the world (since they operate by diff). Is
this enough of an improvement to justify that?

Good point, that's also my concern. E.g. emacs "changelog" mode provides
convenient shortcuts to write Changes files and that's lost when
following CPAN::Changes::Spec.

andreas

[ribasushi]

@andk The discussion is spread. Here is a summary of the metacpan-side issues: metacpan/metacpan-web#948.

My 2c: I personally concluded that in its current form CPAN::Changes::Spec is not something I am accepting patches for on my own projects.

[neilb]

Is this discussion conducted in public?

@andk: I'm writing a post for blogs.perl.org, maybe that can be a single place for discussion?

If it's a knee jerk reaction to metacpan's broken parsing approach [...]

It's not. I came across that a good while after starting this.

[shadowcat-mst]

On Thu, Sep 26, 2013 at 11:17:22PM -0700, andk wrote:

shadowcat-mst [email protected] writes:

Note that there's currently a pull request open to make metacpan parse changes
files in general, and I'm discussing relaxing the spec with the
author.

Is this discussion conducted in public?

For ::Changes I've been prodding bricas on #catalyst-dev since I'm trying
to get him to express an opinion on some formatting and wanting to be
minimally annoying (at least relative to normal for me :).

Riba pointed out the metacpan issue already.

Matt S Trout - Shadowcat Systems - Perl consulting with a commit bit and a clue

http://shadowcat.co.uk/blog/matt-s-trout/ http://twitter.com/shadowcat_mst/

Email me now on mst (at) shadowcat.co.uk and let's chat about how our CPAN
commercial support, training and consultancy packages could help your team.

[neilb]

Blog post: http://blogs.perl.org/users/neilb/2013/09/a-convention-for-changes-files.html

[ribasushi]

@neilbowers As clearly explained by @haarg in the linked metacpan issue - the spec does not really deal in any usable manner with nested changes spanning multiple lines. Also for those of us who release rarely and have large changelogs, the loss of information density and aestethic due to [whitespace enclosed ini-like headers] is a step back.

[neilb]

@ribasushi: I'll read that more closely this evening. I've also been given a list of things to read by @daxim.

I'm not a fan of the [ ... ] section headers myself, but used it on this Changes file to preserve Tim's original structure.

[dagolden]

This is turning into bikeshed painting. :-/

The minimal spec I think should be generally observed is this:

• Version flush left, followed by whitespace, followed by human readable date
• Changes for that version are indented text

That's it! That is entirely sufficient to pick out the entry for a version. With that minimal spec, diffs are unnecessary, which then allows prior entries to be revised for omissions, errors, typos, whatever.

Personally, I favor section headers. The longer the changelog, the more it needs sections. Information density is a problem, not a solution. Imagine if perldeltas had no sections. Horrors!

The ultimate goal should be to maximize human readability. Clustering related changes, ordering by priority, etc. make it easier for people to find relevant sections and ignore others.

But that's my view.

As far as Neil's PR, it achieves my minimal spec of "version left then date on one line, everything else indented" and thus I favor applying it.

[timj]

I'll just note that the Changes file was standard emacs Changelog format (generated automatically with the add-changelog-entry (or whatever) command) so I'm not quite sure what the motivation is for changing it. Saying that, if people want to do this I won't stop them.

[karenetheridge]

I made a less drastic change in commit 1849862. I'll leave this PR open for someone to consider later -- if they rebase to master the diffs should be separated by version and more readable, at least.

[mohawk2]

@neilb Is this still desirable? If not, can it be closed?