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

Open
wants to merge 3 commits into
from

Projects

None yet

7 participants

@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
Perl Toolchain Gang member

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

@dolmen
Perl Toolchain Gang member

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

@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
Perl Toolchain Gang member
@andk
Perl Toolchain Gang member
@ribasushi
Perl Toolchain Gang member

@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
Perl Toolchain Gang member
@ribasushi
Perl Toolchain Gang member

@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
Perl Toolchain Gang member

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment