develooper Front page | perl.perl5.porters | Postings from July 2009

version-0.77 and You

Thread Next
From:
John Peacock
Date:
July 15, 2009 03:15
Subject:
version-0.77 and You
Message ID:
4A5DAC25.6070109@havurah-software.org
Dear Friends (and Enemies) of version.pm -

As you may already be aware, we are on a push to get Perl 5.10.1 out the door.
In support of this, I have updated the version.pm code in both Module::Build and
core Perl (and which has been pulled into maint-5.10).  This is primarily an API
rewrite (renaming qv -> declare and new -> parse), based on some very sensible
suggestions from David Golden+++.  There are a couple of bug fixes (to do with
locales), but the underlying code is largely identical to what shipped in Perl
5.10.0.

However, before I can finalize and release 0.77 to CPAN, the POD must be
rewritten.  I fully and freely admit that the documentation for version.pm has
not had the same care and feeding that the code itself.  And I have a tendency
to be long-winded (c.f. this email).  So I need _your_ help!

I've split the docs into two pieces:

1) version.pod = the bare minimum information that a module author needs to know
to use version.pm in his/her own code

2) version/Internals.pod = all the messy implementation details, internal
representations, etc.

I think that #1 is close, but I've been staring at this code for n+1 years and
my biases are showing.  I would really appreciate anyone who cares about
versioning to take a look at that file and tell me if you can understand it.
Better yet, rewrite some portion of it and send me a diff (and to these two
lists so we don't duplicate effort).

#2 is a largely unchanged copy of the original POD file.  I'm going to take a
chainsaw to it RSN and rip out the bits that are now in #1.  I also have the
beginnings of a simple script to make it easier for a CPAN author to switch from
 decimal to dotted-decimal format, without confusing either themselves or the users.

Any help you can give me, even just a quick read through #1 and a detailed
criticism would be greatly appreciated.  However, this isn't an opportunity to
discuss design decisions; the basic implementation is what it is, it's been
released in Perl 5.10.0 and it _can't_ change now.  We /can/ add compatibility
API (which is what David Golden wisely suggested) that makes it more obvious
what is the right thing to do.

If you want to help, the files are here:

 https://svn.perl.org/modules/version/trunk/lib/version.pod

and

 https://svn.perl.org/modules/version/trunk/lib/version/Internals.pod

or you can just check out

 https://svn.perl.org/modules/version/trunk

to get the whole thing.

Thanks in advance for your assistance...

John

Thread Next


nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About