This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Replace a few http urls with https
[perl5.git] / pod / perlmodstyle.pod
index df813a0..74672ac 100644 (file)
@@ -58,6 +58,10 @@ Do one thing and do it well
 
 Choose an appropriate name
 
+=item *
+
+Get feedback before publishing
+
 =back
 
 =head2 The API
@@ -178,7 +182,9 @@ been done in Perl, and avoid re-inventing the wheel unless you have a
 good reason.
 
 Good places to look for pre-existing modules include
-http://search.cpan.org/ and asking on modules@perl.org
+L<MetaCPAN|https://metacpan.org> and L<PrePAN|http://prepan.org>
+and asking on C<module-authors@perl.org>
+(L<https://lists.perl.org/list/module-authors.html>).
 
 If an existing module B<almost> does what you want, consider writing a
 patch, writing a subclass, or otherwise extending the existing module
@@ -238,11 +244,18 @@ hierarchy already exists under which you could place your module.
 
 =back
 
-You should contact modules@perl.org to ask them about your module name
-before publishing your module.  You should also try to ask people who 
-are already familiar with the module's application domain and the CPAN
-naming system.  Authors of similar modules, or modules with similar
-names, may be a good place to start.
+=head2 Get feedback before publishing
+
+If you have never uploaded a module to CPAN before (and even if you have),
+you are strongly encouraged to get feedback on L<PrePAN|http://prepan.org>.
+PrePAN is a site dedicated to discussing ideas for CPAN modules with other
+Perl developers and is a great resource for new (and experienced) Perl
+developers.
+
+You should also try to get feedback from people who are already familiar
+with the module's application domain and the CPAN naming system.  Authors
+of similar modules, or modules with similar names, may be a good place to
+start, as are community sites like L<Perl Monks|https://www.perlmonks.org>.
 
 =head1 DESIGNING AND WRITING YOUR MODULE
 
@@ -370,7 +383,7 @@ which is visible to the user (and most things that aren't!)
 
 =item Parameter passing
 
-Use named parameters. It's easier to use a hash like this:
+Use named parameters.  It's easier to use a hash like this:
 
     $obj->do_something(
            name => "wibble",
@@ -390,7 +403,7 @@ backward compatibility, and this will probably make your list order
 unintuitive.  Also, if many elements may be undefined you may see the
 following unattractive method calls:
 
-    $obj->do_something(undef, undef, undef, undef, undef, undef, 1024);
+    $obj->do_something(undef, undef, undef, undef, undef, 1024);
 
 Provide sensible defaults for parameters which have them.  Don't make
 your users specify parameters which will almost always be the same.
@@ -566,7 +579,7 @@ Your module should also include a README file describing the module and
 giving pointers to further information (website, author email).  
 
 An INSTALL file should be included, and should contain simple installation 
-instructions. When using ExtUtils::MakeMaker this will usually be:
+instructions.  When using ExtUtils::MakeMaker this will usually be:
 
 =over 4
 
@@ -598,6 +611,11 @@ Release notes or changelogs should be produced for each release of your
 software describing user-visible changes to your module, in terms
 relevant to the user.
 
+Unless you have good reasons for using some other format
+(for example, a format used within your company),
+the convention is to name your changelog file C<Changes>,
+and to follow the simple format described in L<CPAN::Changes::Spec>.
+
 =head1 RELEASE CONSIDERATIONS
 
 =head2 Version numbering
@@ -615,23 +633,26 @@ The most common CPAN version numbering scheme looks like this:
     1.00, 1.10, 1.11, 1.20, 1.30, 1.31, 1.32
 
 A correct CPAN version number is a floating point number with at least 
-2 digits after the decimal. You can test whether it conforms to CPAN by 
+2 digits after the decimal.  You can test whether it conforms to CPAN by 
 using
 
-    perl -MExtUtils::MakeMaker -le 'print MM->parse_version(shift)' 'Foo.pm'
+    perl -MExtUtils::MakeMaker -le 'print MM->parse_version(shift)' \
+                                                            'Foo.pm'
 
 If you want to release a 'beta' or 'alpha' version of a module but
 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
+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
-and convert the string into a number. Later operations that treat
+and convert the string into a number.  Later operations that treat
 $VERSION as a number will then be able to do so without provoking a
 warning about $VERSION not being a number.
 
@@ -639,6 +660,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
@@ -671,7 +699,7 @@ Specify version requirements for other Perl modules in the
 pre-requisites in your Makefile.PL or Build.PL.
 
 Be sure to specify Perl version requirements both in Makefile.PL or
-Build.PL and with C<require 5.6.1> or similar. See the section on
+Build.PL and with C<require 5.6.1> or similar.  See the section on
 C<use VERSION> of L<perlfunc/require> for details.
 
 =head2 Testing
@@ -682,7 +710,8 @@ and the tests should also be available to people installing the modules
 For Module::Build you would use the C<make test> equivalent C<perl Build test>.
 
 The importance of these tests is proportional to the alleged stability of a 
-module. A module which purports to be stable or which hopes to achieve wide 
+module.  A module which purports to be
+stable or which hopes to achieve wide 
 use should adhere to as strict a testing regime as possible.
 
 Useful modules to help you write tests (with minimum impact on your 
@@ -697,8 +726,9 @@ Currently you have the choice between ExtUtils::MakeMaker and the
 more platform independent Module::Build, allowing modules to be installed in a
 consistent manner.
 When using ExtUtils::MakeMaker, you can use "make dist" to create your
-package. Tools exist to help you to build your module in a MakeMaker-friendly
-style. These include ExtUtils::ModuleMaker and h2xs.  See also L<perlnewmod>.
+package.  Tools exist to help you to build your module in a
+MakeMaker-friendly style.  These include ExtUtils::ModuleMaker and h2xs.
+See also L<perlnewmod>.
 
 =head2 Licensing
 
@@ -768,7 +798,7 @@ L<ExtUtils::MakeMaker>, L<Module::Build>
 
 L<Test::Simple>, L<Test::Inline>, L<Carp::Assert>, L<Test::More>, L<Test::MockObject>
 
-=item http://pause.perl.org/
+=item L<https://pause.perl.org/>
 
 Perl Authors Upload Server.  Contains links to information for module
 authors.