Document new strict and lax rules for version numbers

[p5pRT]

Migrated from rt.perl.org#72130 (status was 'resolved')

Searchable as RT72130$

[p5pRT]

From "xdaveg@gmail.com"@vulcan.hyperbolic.net

Created by xdaveg\@gmail.com

Blead now introduces "strict" rules for version numbers in 'package NAME VERSION' and "lax" rules for UNIVERSAL​::VERSION and version->new().

Before 5.12 release\, all these new rules need to be noted in the documentation for these functions/modules.

While the rules for use() are relatively unchanged\, it would be a good idea to add documentation there as well that notes the new standards.

We should consider whether an entirely new documentation file would be helpful in explaining the strict and lax rules (and historical rationale).

-- David

Perl Info

``` Flags: category=docs severity=medium Site configuration information for perl 5.11.3: Configured by david at Sat Jan 16 15:59:57 EST 2010. Summary of my perl5 (revision 5 version 11 subversion 3) configuration: Commit id: b386fa440d8266b7c2eb26f47b6c2a7d315a0128 Platform: osname=linux, osvers=2.6.31-17-generic, archname=x86_64-linux uname='linux vulcan 2.6.31-17-generic #54-ubuntu smp thu dec 10 17:01:44 utc 2009 x86_64 gnulinux ' config_args='-Dusedevel -Dprefix=/opt/perl/fromgit -Dcf_email=xdaveg\@gmail.com -Dperladmin=dagolden\@cpan.org -des -Dcc='ccache gcc'' hint=recommended, useposix=true, d_sigaction=define useithreads=undef, usemultiplicity=undef useperlio=define, d_sfio=undef, uselargefiles=define, usesocks=undef use64bitint=define, use64bitall=define, uselongdouble=undef usemymalloc=n, bincompat5005=undef Compiler: cc='ccache gcc', ccflags ='-fno-strict-aliasing -pipe -fstack-protector -I/usr/local/include -D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64', optimize='-O2', cppflags='-fno-strict-aliasing -pipe -fstack-protector -I/usr/local/include' ccversion='', gccversion='4.4.1', gccosandvers='' intsize=4, longsize=8, ptrsize=8, doublesize=8, byteorder=12345678 d_longlong=define, longlongsize=8, d_longdbl=define, longdblsize=16 ivtype='long', ivsize=8, nvtype='double', nvsize=8, Off_t='off_t', lseeksize=8 alignbytes=8, prototype=define Linker and Libraries: ld='ccache gcc', ldflags =' -fstack-protector -L/usr/local/lib' libpth=/usr/local/lib /lib /usr/lib /lib64 /usr/lib64 libs=-lnsl -ldb -ldl -lm -lcrypt -lutil -lc perllibs=-lnsl -ldl -lm -lcrypt -lutil -lc libc=/lib/libc-2.10.1.so, so=so, useshrplib=false, libperl=libperl.a gnulibc_version='2.10.1' Dynamic Linking: dlsrc=dl_dlopen.xs, dlext=so, d_dlsymun=undef, ccdlflags='-Wl,-E' cccdlflags='-fPIC', lddlflags='-shared -O2 -L/usr/local/lib -fstack-protector' Locally applied patches: @INC for perl 5.11.3: /opt/perl/fromgit/lib/site_perl/5.11.3/x86_64-linux /opt/perl/fromgit/lib/site_perl/5.11.3 /opt/perl/fromgit/lib/5.11.3/x86_64-linux /opt/perl/fromgit/lib/5.11.3 . Environment for perl 5.11.3: HOME=/home/david LANG=en_US.UTF-8 LANGUAGE (unset) LC_COLLATE=C LC_CTYPE=en_US.UTF-8 LD_LIBRARY_PATH (unset) LOGDIR (unset) PATH=.:~/bin:~/git/utility-scripts:/opt/perl/5.10.1/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games PERLPATH=/opt/perl/5.10.1/bin PERL_BADLANG (unset) PERL_EXTUTILS_AUTOINSTALL=--default-deps SHELL=/bin/bash ```

[p5pRT]

From @obra

Blead now introduces "strict" rules for version numbers in 'package NAME VERSION' and "lax" rules for UNIVERSAL​::VERSION and version->new().

Before 5.12 release\, all these new rules need to be noted in the documentation for these functions/modules.

While the rules for use() are relatively unchanged\, it would be a good idea to add documentation there as well that notes the new standards.

We should consider whether an entirely new documentation file would be helpful in explaining the strict and lax rules (and historical rationale).

I saw that you committed docs yesterday or the day before. Do you feel like what we have is now sufficient?

[p5pRT]

The RT System itself - Status changed from 'new' to 'open'

[p5pRT]

From @xdg

I saw that you committed docs yesterday or the day before. Do you feel like what we have is now sufficient?

No. The documentation for version.pm needs to more formally describe the rules and the new functions is_strict and is_lax need documentation as well.

-- David

[p5pRT]

From @JohnPeacock

On 01/16/2010 04​:32 PM\, "xdaveg@​gmail.com"@​vulcan.hyperbolic.net (via RT) wrote​:

Blead now introduces "strict" rules for version numbers in 'package NAME VERSION' and "lax" rules for UNIVERSAL​::VERSION and version->new().

Before 5.12 release\, all these new rules need to be noted in the documentation for these functions/modules.

First pass at documenting $version​::LAX and $version​::STRICT

http​://github.com/JohnPeacock/perl/tree/document_version_strict_lax git​://github.com/JohnPeacock/perl.git branch document_version_strict_lax

I'm in the midst of rewriting the pure Perl implementation for CPAN to be more like the XS code\, but there is no reason to hold up nailing down the core changes now.

John

[p5pRT]

From @xdg

On Tue\, Jan 26\, 2010 at 9​:30 PM\, John Peacock \john\.peacock@​havurah\-software\.org wrote​:

git​://github.com/JohnPeacock/perl.git branch document_version_strict_lax

I wish git had a better syntax for referring to branches or other reference points. E.g.​:

  git​://github.com/JohnPeacock/perl.git#document_version_strict_lax

If anyone in the LazyWeb is close enough to git development to suggest standardizing git URIs in such a fashion\, that would be lovely.

David

[p5pRT]

From @xdg

[copying my comments from another p5p thread]

I still think that version number documentation is more dense than I'd like it to be\, but I'm two weeks behind on CPAN Tester 2.0 and I don't have the round tuits to figure out what it needs or do any editing myself. Maybe it's inevitable given the complexity of the topic.

My quick notes are​:

* VERSION OBJECT DETAILS should move to version​::Internals (to the extent it isn't already covered there) and a very brief note about how alpha versions compare be added to the section "How to compare version objects"; that leaves version.pod entirely focused on how to get things done. It's then a "cookbook" with some method/function docs and I think that's all 99.99% of people will ever need.

* Add an OTHER FUNCTIONS section with is_strict() and is_lax() for completeness.

* In version​::Internals\, remove the SUBCLASSING section or else leave it and add text discouraging people from subclassing and remove reference to version​::AlphaBeta (in fact\, I recommend deleting that module from CPAN).

[p5pRT]

From @xdg

I've taken John's work\, made the changes I suggested above (plus some other minor cleanup and doc tweaks) and pushed the result to blead​:

  6369c73 move version details to version​::Internals and other clean up   a525e6d document version​::is_strict/is_lax   42bd538 Document usage of version regexps   61a0cb1 Export and document is_lax and is_strict functions

Unless John has objections\, I believe this ticket can be closed and the new documentation can be pulled into the next CPAN release of version.pm.

-- David

[p5pRT]

From @JohnPeacock

On 02/06/2010 03​:14 PM\, David Golden via RT wrote​:

I've taken John's work\, made the changes I suggested above (plus some other minor cleanup and doc tweaks) and pushed the result to blead​:

6369c73 move version details to version​::Internals and other clean up a525e6d document version​::is_strict/is_lax 42bd538 Document usage of version regexps 61a0cb1 Export and document is_lax and is_strict functions

Unless John has objections\, I believe this ticket can be closed and the new documentation can be pulled into the next CPAN release of version.pm.

Close away\, I'm sure that what you wrote was fine. I've just emerged from Snowmageddon 2010 - 36 hours with no power or heat or Internet \.

I'll pull it into version.pm as soon as I get a chance. I'm inclined to bump $VERSION to 0.82 in core and then pick up the remaining doc changes (and the return value optimizations that I missed somehow) and push a new CPAN release.

John

[p5pRT]

From @xdg

Closing this ticket.

[p5pRT]

@xdg - Status changed from 'open' to 'resolved'