CPAN Cleaning Day 2457027: Changes and README
I spent another day of prosaic adjustments to my CPAN distributions. For quite awhile the chaos of the Changes and README files have bothered me, so I wanted to think about those. And, many of the files I scheduled for deletion disappeared from PAUSE today.
I'd like Changes to have structured information that a program can turn into a data structure (and query, such as "What version fixed GitHub issue #137?". We don't quite have that, but there is the start of a specification in CPAN::Changes::Spec and a test module, Test::CPAN::Changes to check it. There's even a Changes Kwalitee at CPAN HQ. I'm not doing so well at the moment. Dave Rolsky has some thoughts on Changes files too. Of course, Neil has already written about it in A convention for Changes files, and Jonas covers many of the same things.
The README file is a different story and I haven't decided what I want to do about that. This file used to be the thing you would look at before you wasted your modem time download those large, 15k distributions. Then, they weren't so useful. Now, however, GitHub displays their contents. I want to make mine prettier and to evaluate the information I put in them.
There's a Test::CPAN::README, but it checks for merely a name and version. I don't particularly care about the version since I envision a file with stable information such as the summary of its use, the basics of finding the source, and how to contribute. I expect those to stay the same almost forever. Whatever I put in there, I want it to look good for GitHub. I might even consider using GitHub Pages like I did for Perl Power Tools. I had fun playing with that at Saint Perl 6.
I'm the author of Mastering Perl, and the co-author of Learning Perl (6th Edition), Intermediate Perl, Programming Perl (4th Edition) and Effective Perl Programming (2nd Edition).
Years ahead of you! ;-)
Go to a SPARQL endpoint, and type in the following as the default graph URI (this is a link to a bunch of RDF data that I typically bundle with my distributions):
And the following SPARQL query (SPARQL is an SQL-like language for querying RDF):
PREFIX doap: <http://usefulinc.com/ns/doap#> PREFIX bug: <http://ontologi.es/doap-bugs#> PREFIX change: <http://ontologi.es/doap-changeset#> PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#> SELECT * WHERE { $release doap:revision $revision; change:changeset [ change:item [ rdfs:label $changelabel; change:fixes [ bug:id "92571" ]; ]; ] }And lastly choose "Retrieve remote RDF data for all missing source graphs" from the drop-down menu under "Sponging".
Then hit "Run Query" (the button is annoyingly at the top).
If you enjoyed that, then take a look at Greg Williams' CPAN account (CPAN:GWILLIAMS) - he has been pushing out world-beating RDF libraries written in Perl for years, which should be perfectly capable of running queries such as the above on any of my distributions.
Here's another query to play with. Same source graph, same sponging options.
PREFIX doap: <http://usefulinc.com/ns/doap#> PREFIX bug: <http://ontologi.es/doap-bugs#> PREFIX change: <http://ontologi.es/doap-changeset#> PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#> SELECT * WHERE { $release doap:revision $revision; change:changeset [ change:item [ rdfs:label $changelabel; change:fixes [ rdfs:label $buglabel ]; ]; ]. FILTER( regex($buglabel, "Boiler\\s*Plate", "i") || regex($changelabel, "Boiler\\s*Plate", "i") ) }kentnl++ just turned my README wishlist (/ IRC kvetching) into code: Dist::Zilla::Plugin::Readme::Brief. An example of its output is the plugin’s own README.