Beefy Boxes and Bandwidth Generously Provided by pair Networks
Do you know where your variables are?
 
PerlMonks  

VERSION section in POD

by polettix (Vicar)
on May 18, 2016 at 13:08 UTC ( #1163338=perlquestion: print w/replies, xml ) Need Help??
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 any feedback!

perl -ple'$_=reverse' <<<ti.xittelop@oivalf

Io ho capito... ma tu che hai detto?

Replies are listed 'Best First'.
Re: VERSION section in POD
by choroba (Bishop) on May 18, 2016 at 14:16 UTC
    I use perl-reversion for my modules. I usually just -bump the VERSION and it happens everywhere, I just have not to forget to commit the changes.

    I still feel there must be a better way (see for example line 27 of Makefile.PL here, it's ugly). There's the third place where you need the version!

    ++Thanks for asking the question.

    ($q=q:Sq=~/;[c](.)(.)/;chr(-||-|5+lengthSq)`"S|oS2"`map{chr |+ord }map{substrSq`S_+|`|}3E|-|`7**2-3:)=~y+S|`+$1,++print+eval$q,q,a,
      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?

      perl -ple'$_=reverse' <<<ti.xittelop@oivalf

      Io ho capito... ma tu che hai detto?
      Interesting. I couldn't help but notice that perl-reversion is not versioned in the source or POD. Maybe that is the right approach?
        It's just an example script in the Perl::Version distribution, whose main module is versioned in both the code and pod.

        ($q=q:Sq=~/;[c](.)(.)/;chr(-||-|5+lengthSq)`"S|oS2"`map{chr |+ord }map{substrSq`S_+|`|}3E|-|`7**2-3:)=~y+S|`+$1,++print+eval$q,q,a,
Re: VERSION section in POD
by LanX (Bishop) on May 18, 2016 at 15:27 UTC
    I once wrote a little script ("podbuilder") creating a .pod file for my module (and manifest, README and so on) from templates.

    ( because perldoc <MODULE> will show the content of <MODULE>.pod (if present) instead of <MODULE>.pm )

    It also does a parsing of my module's POD for comments which are meant to be part of the interface description including $VERSION

    Since the script is part of the test suite and/or commit-hook all files are automatically updated.

    So instead of "reversioning" all files I only update the main code's $VERSION. ²

    But I have to admit I never really used Pod::Weaver or Dist::Zilla , so I can't tell how many wheels I reinvented, BUT it has no dependencies³.

    Cheers Rolf
    (addicted to the Perl Programming Language and ☆☆☆☆ :)
    Je suis Charlie!

    ²) which shouldn't be done without running the test-suite anyway

    ³) which means I can distribute it with my module, without blowing up the dependencies.

      It would be interesting to take a look at it, for inspiration...

      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.

      perl -ple'$_=reverse' <<<ti.xittelop@oivalf

      Io ho capito... ma tu che hai detto?
Re: VERSION section in POD
by afoken (Abbot) on May 18, 2016 at 17:51 UTC
      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.

      perl -ple'$_=reverse' <<<ti.xittelop@oivalf

      Io ho capito... ma tu che hai detto?
        All in all, I'm getting from the feedbacks to this thread that a few people find value in keeping VERSION in POD too

        Having the version number of the module in the module's documentation is important to the reader for knowing which version the documentation applies to.

Re: VERSION section in POD
by RonW (Vicar) on May 18, 2016 at 16:56 UTC

    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.

    It can also parse the package statement to generate the NAME section.

      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):
      abstract = Text and data canalising [CopyFilesFromRelease/Tubergen] filename = script/tubergen [@Milla] Git::Check.allow_dirty = script/tubergen Git::Commit.allow_dirty = script/tubergen [Run::AfterBuild] run = support/podversion.pl "%d" "%v" run = support/tubergen-bundle.pl "%d" "%v" [PruneFiles] filename = cpanfile.snapshot match = ^support/

      Good to know that others see value in the VERSION section, anyway, so thanks for taking the time!

      perl -ple'$_=reverse' <<<ti.xittelop@oivalf

      Io ho capito... ma tu che hai detto?

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

Re: VERSION section in POD
by jandrew (Chaplain) on May 19, 2016 at 00:36 UTC

    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.

    =begin html <a href="https://www.perl.org"> <img src="https://img.shields.io/badge/perl-5.10+-brightgreen.svg" + alt="perl version"> </a> <a href="https://travis-ci.org/jandrew/p5-spreadsheet-reader-excelxml" +> <img alt="Build Status" src="https://travis-ci.org/jandrew/p5-spre +adsheet-reader-excelxml.png?branch=master" alt='Travis Build'/> </a> <a href='https://coveralls.io/github/jandrew/p5-spreadsheet-reader-exc +elxml?branch=master'> <img src='https://coveralls.io/repos/github/jandrew/p5-spreadsheet +-reader-excelxml/badge.svg?branch=master' alt='Coverage Status' /> </a> <a href='https://github.com/jandrew/p5-spreadsheet-reader-excelxml'> <img src="https://img.shields.io/github/tag/jandrew/p5-spreadsheet +-reader-excelxml.svg?label=github version" alt="github version"/> </a> <a href="https://metacpan.org/pod/Spreadsheet::Reader::ExcelXML"> <img src="https://badge.fury.io/pl/Spreadsheet-Reader-ExcelXML.svg +?label=cpan version" alt="CPAN version" height="20"> </a> <a href='http://cpants.cpanauthors.org/dist/Spreadsheet-Reader-ExcelXM +L'> <img src='http://cpants.cpanauthors.org/dist/Spreadsheet-Reader-Ex +celXML.png' alt='kwalitee' height="20"/> </a> =end html

    For the github badge to work you have to draft a release with the package version as the 'Tag version'

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

      Definitely goes into my "Today I Learned..." bucket, thanks!

      perl -ple'$_=reverse' <<<ti.xittelop@oivalf

      Io ho capito... ma tu che hai detto?

      Looking at this more closely, it appears to always link to the info about the latest version instead of the version "in hand".

      Still, this is interesting.

        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!!

Log In?
Username:
Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: perlquestion [id://1163338]
Approved by Corion
Front-paged by LanX
help
Chatterbox?
and all is quiet...

How do I use this? | Other CB clients
Other Users?
Others studying the Monastery: (4)
As of 2018-06-24 00:04 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?
    Should cpanminus be part of the standard Perl release?



    Results (126 votes). Check out past polls.

    Notices?