Including Changes information in POD
Is including Changes information in main module's POD a good idea?
You bet. Typing "man Foo" or "perldoc Foo" beats having to go to search.cpan.org or metacpan.org and search for Foo and click some more. Or having to download the distribution, extract the tarball, and viewing the Changes file.
Well, actually, it's a good idea as long as module authors don't have to do it manually.
So, Pod::Weaver::Section::Changes. Example Changes POD section. Enjoy.
UPDATE 2012-09-07: I changed my mind :) After creating an alias chg to a command that views Changes in my local repositories, and chgr to cpan-listchanges, I no longer find Changes in the POD appealing. So all I needed was an easy access to Changes.
A programmer (mostly Perl 5 nowadays).
My CPAN ID: SHARYANTO. I'm sedusedan on perlmonks. My twitter is stevenharyanto (but I don't tweet much). Follow me on github: sharyanto.
I love the idea to have an easy way to get the changelog of a distribution (I think there's an app somewhere that can get it straight from CPAN (or your local darkpan mirror), but to have it really locally is appealing). I'm less in love with having it in the POD directly, as it can add a lot of noise.
I'm thinking of two possible alternatives (caveat emptor: that's 2 minutes worth of musing, so take with a grain of salt):
(1) For any dist (eg, Foo::Bar), have Foo::Bar::Changes which is nothing but the podified changelog.
(2) in Foo::Bar have the changelog, but with =begin changelog ... =end, so that it can be extracted if wished, but is generally invisible.
Hi Yanick,
Thanks for the comment. Yeah, agree about the potential noise. I'm adding the Changes into POD of selected modules for now, where I need to check for the changes often :)
@yanick I think #1 is a good idea, especially if you link to it from a CHANGES section from within the main POD. That way, if you want to see the changes, just follow the link!
Two additional mini-thoughts about the Changes as an additional module/POD:
1) The canonical name could be Foo::Bar::changelog with a lowercase to ensure it doesn't interfere with the regular modules (and, more to the point, a visual distinction).
2) The changelog should be a .pod, not a .pm, again to be visible, but not to trample in the module space more than we need.
All good. I would prefer Foo::Bar::changes over ::changelog. And absolutely, make it a .pod instead of a .pm.
Also, CPAN clients (or their plugin) could create this during installation, so module authors need not deal with this.
Yup, there's App::cpanlistchanges by MIYAGAWA.
Sweet.
I hate seeing changes in the POD. The POD is just how the fucking thing works! If I want to see the list of changes you've done, I would prefer a specific file containing just that, the way most *nix applications do it. Hey, wait a minute! How about calling it "Changelog" or "Changes" or "CHANGES"?
I have to dissent as well. Whether you put them in a separate
.podor (preferrably, IMO) do nothing and usecpan-listchangesinstead – no matter, pick according to your tastes, but please: do not make a habit of putting the changelog in the documentation.You could write a Dist::Zilla plugin if you go the separate
.podroute.