polettix has asked for the
wisdom of the Perl Monks concerning the following question:

Hi!

I use to include a VERSION section in the main module of the distributions uploaded to CPAN, but this comes at the risk of forgetting to update the number.

Over time, I adopted different strategies, ranging from doing it manually (guess what happened), to using Dist::Zilla all the way down to Pod::Weaver (which I really never liked), to switching to Milla and inserting a custom mangling script in an AfterBuild step (example dist.ini and mangling script if you're curious). This mostly works, but it's giving me issues in a corner case in Travis-CI which brought me to ask myself whether I still want it or not.

I somehow like the idea of including that section, so that anyone looking at the documentation can get an idea of what docs they are reading without resorting to hoop jumping (my favorite incantation being perldoc -m Module::Name and then looking for $VERSION). Spending additional effort on my custom mangling script is not something that attracts me too much. So I'd ask your advice about:

does including a VERSION section really provide value in your opinion?

is there any "evident" way to do automate that using Milla? Alas, it seems that miyagawa does not usually include that section (not in the ones I sampled, anyway), so there's no evident way for me to do this!

Thanks for pointing out perl-reversion, it's worth trying/considering as a substitute of my munging process.

Re the third place, that part is actually taken care automatically by Dist::Zilla or Milla, so that is not a problem in my context. These tools are amazing at freeing my mind from most of the workflow!

I get it that you also value a VERSION section in the POD. I wonder how useful/used it is though?

The dependencies observation hits the nail right in the head, as the whole thread started (in my mind at least) from a dependency error I was having in Travis-CI for a corner case. I'm currently using a small templating system to do the job, although it's probably way overkill. I might embed the templating system in the transformation program or... avoid using it.

Quite "hacky" but I enjoyed reading the thread - too bad I didn't find it before pestering you monks.

I forgot to say (my bad) that lately I like to keep my POD in a separate .pod file, so that modules come to be tighter when I do a fatpack-like operation (without the need to do the stripping on the fly, which is mangling the file's contents, which always makes me feel nervous. This is another story though).

The testing alternative proposed by tinita in Re: Don't Repeat Your version number has the advantage of forcing me to update the version number in the POD, which is something that really happens only at release time so it's no big deal actually. On the other hand, I'm really lazy and I'm using automatic update in the Perl sources already (so much for my nervousness), so a simple automation on the POD is already below the threshold of what I'm implicitly inclined to accept.

All in all, I'm getting from the feedbacks to this thread that a few people find value in keeping VERSION in POD too, which is good to know by itself.

I wrote 1119138 to generate a pod file for my Perl programs and modules. I have since updated it to include a new kind of Perl6 comment. (as LanX pointed out, where there is both a Module.pm and Module.pod perldoc will use Module.pod (same is true for metacpan.org))

Among other things, it parses the $VERSION = 1.23; statement to generate the VERSION section in the pod file.

Getting the version number to put in the POD is not a problem, as it's already available in Dist::Zilla/Milla when I call the transformation script in dist.ini (that's %v inside the Run::AfterBuild section):

The reason I wrote the "documentation comments" to POD converter was POD, in Perl5, requires repeating a lot of information that is already present in the code. In Perl6, Pod has an enhanced syntax that allows to referring to information in the surrounding code. Though I didn't know that when I wrote my converter.

The reason I chose to convert from Doxygen style comments was that I already use Doxygen for producing the "low level" design documentation in C/C++, which is what is used at many companies producing electronic control modules. Advantages of doing this include most of the function prototypes and data structures are in place by the time the design is approved, and all of the (text of the) documentation is in the comments of the code, so is much easier to keep the docs and code in sync as changes get made. And, of course, no repeating information that's already in the code (unless you count the descriptions of what the code is supposed to do as repeating the code).

I've started adding the following badge section to my top level module pod so information is provided but maintenance is not required. This includes the minimum perl supported, current github version, CPAN version, Travis-CI state, Coveralls information, and Kwalitee score for that package.

Probably overkill but once it's set up you don't have to mess with it anymore. The down side is it will only display in browsers not in man pages. Inspect the various specific urls for your implementation substitutions. I generally put it right after the NAME section.

This is a very interesting idea. As you correctly point out, it's available in the browser only (so it deviates a bit from what I had in mind in the first place), but it's neat indeed and worth considering (the badges in your modules' pages in metacpan are awesome).

RonW you are correct that the links as shown will always give the latest versions. It is possible to hard code the versions and links to their repos into each badge. See the perl version badge for an example that does just that. Shields.io is a pretty flexible resource for a lot of things in that area. If you do that you're back to the the original issue of having to hand roll the versions in the pod or use a tool like the one suggested by choroba++ (perl-reversion). All/most/(all the good) Pod readers explicitly strip dynamic code for safety. This includes anything that would import the value for the $VERSION variable. I think that perl-reversion or something like it is a good idea I just went down a different path. I suppose my initial post was mostly responding to the part of the OP that asked how other people handle version in their pod. I don't have any compelling reason to say my way is best practice. It's just the way I do it. I suppose that with some work and a parser you could have both hard coded badges and text versions posted I just never went that far. TIMTOWTDI!!