This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perlmod and perlstyle improvements
authorEd J <etj@cpan.org>
Tue, 16 Sep 2014 06:06:23 +0000 (07:06 +0100)
committerFather Chrysostomos <sprout@cpan.org>
Thu, 25 Sep 2014 04:54:38 +0000 (21:54 -0700)
• Outward links for perlmod
• Tweak perlmodstyle version notes
• Link perlnewmod to perlmodstyle

pod/perlmod.pod
pod/perlmodstyle.pod
pod/perlnewmod.pod

index f708cc0..0ed4bd9 100644 (file)
@@ -4,6 +4,27 @@ perlmod - Perl modules (packages and symbol tables)
 
 =head1 DESCRIPTION
 
+=head2 Is this the document you were after?
+
+There are other documents which might contain the information that you're
+looking for:
+
+=over 2
+
+=item This doc
+
+Perl's packages, namespaces, and some info on classes.
+
+=item L<perlnewmod>
+
+Tutorial on making a new module.
+
+=item L<perlmodstyle>
+
+Best practices for making a new module.
+
+=back
+
 =head2 Packages
 X<package> X<namespace> X<variable, global> X<global variable> X<global>
 
index 5622d32..5a52eaf 100644 (file)
@@ -630,9 +630,9 @@ don't want CPAN.pm to list it as most recent use an '_' after the
 regular version number followed by at least 2 digits, eg. 1.20_01. If
 you do this, the following idiom is recommended:
 
-  $VERSION = "1.12_01";
-  $XS_VERSION = $VERSION; # only needed if you have XS code
-  $VERSION = eval $VERSION;
+  our $VERSION = "1.12_01"; # so CPAN distribution will have right filename
+  our $XS_VERSION = $VERSION; # only needed if you have XS code
+  $VERSION = eval $VERSION; # so "use Module 0.002" won't warn on underscore
 
 With that trick MakeMaker will only read the first line and thus read
 the underscore, while the perl interpreter will evaluate the $VERSION
@@ -644,6 +644,13 @@ Never release anything (even a one-word documentation patch) without
 incrementing the number.  Even a one-word documentation patch should
 result in a change in version at the sub-minor level.
 
+Once picked, it is important to stick to your version scheme, without
+reducing the number of digits. This is because "downstream" packagers,
+such as the FreeBSD ports system, interpret the version numbers in
+various ways. If you change the number of digits in your version scheme,
+you can confuse these systems so they get the versions of your module
+out of order, which is obviously bad.
+
 =head2 Pre-requisites
 
 Module authors should carefully consider whether to rely on other
index 7555f97..26c4c13 100644 (file)
@@ -23,6 +23,9 @@ trying to do, and you've had to write the code yourself, consider
 packaging up the solution into a module and uploading it to CPAN so that
 others can benefit.
 
+You should also take a look at L<perlmodstyle> for best practices in
+making a module.
+
 =head2 Warning
 
 We're going to primarily concentrate on Perl-only modules here, rather