Various minor tweaks to follow conventions

[neilb]

Hi Mike,

These changes started with wanting to get this distribution "CPANTS clean", but I did some other changes, including adding a SEE ALSO section, with links to other throttling modules.

Cheers,
Neil

[mschilli]

Very nice, I like that the layout is more standardized, one question on the release notes: I've been using this format

0.06 (2013/05/23)
(ms) [rt.cpan.org 85325] Added better diagnostics in case locking
of db_file fails, as suggested by Nigel Horne.

to indicate who applied the individual patch (ms in this case), while the new layout seems to put the CPAN ID at the top, indicating who released the whole bunch. In case several committers are preparing a release consisting of different patches, how would you be able to glance that information?

[neilb]

I should make clear that putting the PAUSE id on the release line is not defined by CPAN::Changes::Spec, but is a convention that some people follow, including me.

Where people have contributed one or more items in a release, I acknowledge them within the text of the item. For example see the Changes file for Module::Path.

[mschilli]

Yeah, the release PAUSE id is one thing, but the committer who merges the patch of a contributor is another. Let's say there's committers A and B on the project and there's a patch by person C which committer B merges. How would the release notes reflect the fact that it was B and not A who merged C's patch?

[neilb]

I would just note that in the individual bullet point within the release. So you might get something like:

1.12 2015-01-27 FREDB
    - Fix memory leak caused by graphs. Fix from BILLG++, merged by DONATELLO.

[mschilli]

That introduces a lot of redundancy, though, and is harder to view at a glance. Why not replace the generic "-" by something meaningful, like FIXEDBY[:MERGEDBY]?

[neilb]

I think that is harder to scan for most potential readers, who I'd argue are only really interested in the "Fix memory leak caused by graphs" part, and not the rest. So keeping the leftmost part clean and simple to scan would be one of my goals.

Feel free to just close this, though I'm happy to gently ping-pong it discussing the finer details of Changes formatting :-)

Cheers,
Neil