search

ingydotnet / yaml-pm

YAML Perl Module
http://search.cpan.org/dist/YAML/
20 stars 27 forks source link

[meta] Clearer changelogs please? #173

Closed kentfredric closed 6 years ago

kentfredric commented 7 years ago

As a maintainer is very furstrating reading a changelog and seeing:

  *  Apply PR/171 (fixes issue/109) @perlpunk++
  *  No more "used only once" warnings for $YAML::Indent etc.
  *  Apply PR/170 (fixes issue/131) hiratara@cpan.org++
  *  Empty mapping value at the end resolves to null (was becoming empty string)
  *  Apply PR/169 (PR/119) patrick.allen.higgins@gmail.com++
  *  Output key in warning when duplicate key was found
  *  Apply PR/157 and PR/168 (@lameventanas++ @perlpunk++)
  *  Allow reading and writing to IO::Handle

Most of this is because many people reference PR's without giving a summary, and that's very confusing, and this looks like that, where you've interspersed "fixed PR X" lines with other fixes, leaving me wondering "ok, so what is PR/171?!?!" and having to look it up.

Except in your case, it turns out you're using 2-lines per entry with seperate bullet points.

I'd propose something clearer like:

  *  No more "used only once" warnings for $YAML::Indent etc: #171 (fixes #109) @perlpunk++
  *  Empty mapping value at the end resolves to null (was becoming empty string): #170 (fixes #131) hiratara@cpan.org++
  *  Output key in warning when duplicate key was found: #169, #119 patrick.allen.higgins@gmail.com++
  *  Allow reading and writing to IO::Handle: #157 and #168 (@lameventanas++ @perlpunk++)

The idea being to give the most relevant information first, and encourage people only to dig if the relevant information is insufficient.

Also, note in my example I stripped "issue/" and "PR/", mostly because github uses a single sequence for both, and all those prefixes do is impede the ability for MetaCPAN to reference your ticket.

An alternative idea might also be: 

  *  No more "used only once" warnings for $YAML::Indent etc.
     #171 (fixes #109) @perlpunk++

  *  Empty mapping value at the end resolves to null (was becoming empty string)
     #170 (fixes #131)  hiratara@cpan.org++

  *  Output key in warning when duplicate key was found
     #169, #119 patrick.allen.higgins@gmail.com++

  *  Allow reading and writing to IO::Handle:
     #157 and #168 (@lameventanas++ @perlpunk++)

The approach here trying harder to group related entries and only have a bullet point per entry.

perlpunk commented 6 years ago

I modified the changelog. Since the changes are written in YAML format, I prefix the issues/PRs with PR#number or Issue#number to avoid having to quote it. It's still turned into links on metacpan. I added information to the PRs where it was missing. Will be in the next version.