Skip Menu |
 

This queue is for tickets about the CGI-Simple CPAN distribution.

Report information
The Basics
Id: 132519
Status: new
Priority: 0/
Queue: CGI-Simple

People
Owner: Nobody in particular
Requestors: KENTNL [...] cpan.org
Cc:
AdminCc:

Bug Information
Severity: (no value)
Broken in: (no value)
Fixed in: (no value)



Subject: Functionally unhelpful changelog
Many of the notes in the changelog in this range are pretty much a waste of text, especially for people who might be getting copies of this file to read in an offline scenario:

https://metacpan.org/source/MANWAR/CGI-Simple-1.25/Changes#L3-49

Please, do try to itemize the actual changes that may impact end users.

Each line I'm asking myself
- Ok, where is that bug tracked?  (Assume somebody outside the perl ecosystem is reading it )
- Ok, what's the likelihood that where this bug was tracked has changed since a line in the release notes about it was added, and now it no longer references the issue?
- What actual change happened here?
- Should I be cautious about my code needing to be changed?

This present format omits pretty much all the useful details, and leaves only breadcrumbs that only the most committed will be able to break down and understand.

Like for instance, this: https://github.com/manwar/CGI--Simple/pull/9  is  the sort of thing one wants to see mentioned explicitly in the changelog, as is, they see "merged a PR" and it could be a trivial doc change, or a complex and breaking feature change.



-- 
- CPAN kentnl@cpan.org
- Gentoo Perl Maintainer kentnl@gentoo.org ( perl@gentoo.org )

Also, as a conceptual note, the important part of a "change log" is the "change", not the bug or PR you can go to for in-depth details.

Having a bug ID/PR associated with each entry should be considered an *addition* to the content, with much lower priority. ( I'd rather a change entry with no bug ref, than a bug ref with no description )

That's why the conventional pattern is:

 

   - here's what we changed  (Bug #1254677)

Not:

  - Fixed bug #12345 ( here's what we changed )



-- 
- CPAN kentnl@cpan.org
- Gentoo Perl Maintainer kentnl@gentoo.org ( perl@gentoo.org )
 



This service is sponsored and maintained by Best Practical Solutions and runs on Perl.org infrastructure.

Please report any issues with rt.cpan.org to rt-cpan-admin@bestpractical.com.