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 or 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.


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.

@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.

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 .pod or (preferrably, IMO) do nothing and use cpan-listchanges instead – 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 .pod route.

Leave a comment

About Steven Haryanto

user-pic 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.