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 bbf6366..74672ac 100644 (file)
@@ -58,6 +58,10 @@ Do one thing and do it well
 
 Choose an appropriate name
 
 
 Choose an appropriate name
 
+=item *
+
+Get feedback before publishing
+
 =back
 
 =head2 The API
 =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
 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
 
 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
 
 
 =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
 
 
 =head1 DESIGNING AND WRITING YOUR MODULE
 
@@ -260,50 +273,50 @@ right fit for your problem:
 
 =over 4
 
 
 =over 4
 
-=item
+=item *
 
 The system being designed is large, or is likely to become large.
 
 
 The system being designed is large, or is likely to become large.
 
-=item
+=item *
 
 The data can be aggregated into obvious structures, especially if
 there's a large amount of data in each aggregate.
 
 
 The data can be aggregated into obvious structures, especially if
 there's a large amount of data in each aggregate.
 
-=item
+=item *
 
 The various types of data aggregate form a natural hierarchy that
 facilitates the use of inheritance and polymorphism.
 
 
 The various types of data aggregate form a natural hierarchy that
 facilitates the use of inheritance and polymorphism.
 
-=item
+=item *
 
 You have a piece of data on which many different operations are
 applied.
 
 
 You have a piece of data on which many different operations are
 applied.
 
-=item
+=item *
 
 You need to perform the same general operations on related types of
 data, but with slight variations depending on the specific type of data
 the operations are applied to.
 
 
 You need to perform the same general operations on related types of
 data, but with slight variations depending on the specific type of data
 the operations are applied to.
 
-=item
+=item *
 
 It's likely you'll have to add new data types later.
 
 
 It's likely you'll have to add new data types later.
 
-=item
+=item *
 
 The typical interactions between pieces of data are best represented by
 operators.
 
 
 The typical interactions between pieces of data are best represented by
 operators.
 
-=item
+=item *
 
 The implementation of individual components of the system is likely to
 change over time.
 
 
 The implementation of individual components of the system is likely to
 change over time.
 
-=item
+=item *
 
 The system design is already object-oriented.
 
 
 The system design is already object-oriented.
 
-=item
+=item *
 
 Large numbers of other programmers will be using your code modules.
 
 
 Large numbers of other programmers will be using your code modules.
 
@@ -370,7 +383,7 @@ which is visible to the user (and most things that aren't!)
 
 =item Parameter passing
 
 
 =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",
 
     $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:
 
 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.
 
 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 
 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
 
 
 =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.
 
 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
 =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 
     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
 
 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
 
 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:
 
 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
 
 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.
 
 $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.
 
 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
 =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
 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
 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 
 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 
 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
 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
 
 
 =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>
 
 
 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.
 
 Perl Authors Upload Server.  Contains links to information for module
 authors.