Choose an appropriate name
+=item *
+
+Get feedback before publishing
+
=back
=head2 The API
=item *
-Specify pre-requisites in Makefile.PL
+Specify pre-requisites in Makefile.PL or Build.PL
=item *
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
+L<http://search.cpan.org/> and L<https://metacpan.org>
+and asking on C<module-authors@perl.org>
+(L<http://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
rather than rewriting it.
=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|http://www.perlmonks.org>.
=head1 DESIGNING AND WRITING YOUR MODULE
of interfaces available. There are pros and cons of each technique, which
should be considered when you design your API.
-According to Damian Conway, you should consider using OO:
+In I<Perl Best Practices> (copyright 2004, Published by O'Reilly Media, Inc.),
+Damian Conway provides a list of criteria to use when deciding if OO is the
+right fit for your problem:
=over 4
-=item *
+=item *
-When the system is large or likely to become so
+The system being designed is large, or is likely to become large.
-=item *
+=item *
-When the data is aggregated in obvious structures that will become objects
+The data can be aggregated into obvious structures, especially if
+there's a large amount of data in each aggregate.
-=item *
+=item *
-When the types of data form a natural hierarchy that can make use of inheritance
+The various types of data aggregate form a natural hierarchy that
+facilitates the use of inheritance and polymorphism.
=item *
-When operations on data vary according to data type (making
-polymorphic invocation of methods feasible)
+You have a piece of data on which many different operations are
+applied.
=item *
-When it is likely that new data types may be later introduced
-into the system, and will need to be handled by existing code
+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 *
-When interactions between data are best represented by
-overloaded operators
+It's likely you'll have to add new data types later.
=item *
-When the implementation of system components is likely to
-change over time (and hence should be encapsulated)
+The typical interactions between pieces of data are best represented by
+operators.
=item *
-When the system design is itself object-oriented
+The implementation of individual components of the system is likely to
+change over time.
=item *
-When large amounts of client code will use the software (and
-should be insulated from changes in its implementation)
+The system design is already object-oriented.
=item *
-When many separate operations will need to be applied to the
-same set of data
+Large numbers of other programmers will be using your code modules.
=back
=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",
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.
giving pointers to further information (website, author email).
An INSTALL file should be included, and should contain simple installation
-instructions (usually "perl Makefile.PL; make; make install").
+instructions. When using ExtUtils::MakeMaker this will usually be:
+
+=over 4
+
+=item perl Makefile.PL
+
+=item make
+
+=item make test
+
+=item make install
+
+=back
+
+When using Module::Build, this will usually be:
+
+=over 4
+
+=item perl Build.PL
+
+=item perl Build
+
+=item perl Build test
+
+=item perl Build install
+
+=back
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
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'
-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 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
+you do this, the following idiom is recommended:
+
+ 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
+$VERSION as a number will then be able to do so without provoking a
+warning about $VERSION not being a number.
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
=back
Specify version requirements for other Perl modules in the
-pre-requisites in your Makefile.PL.
+pre-requisites in your Makefile.PL or Build.PL.
-Be sure to specify Perl version requirements both in Makefile.PL and
-with C<require 5.6.1> or similar.
+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
+C<use VERSION> of L<perlfunc/require> for details.
=head2 Testing
-All modules should be tested before distribution (using "make disttest",
+All modules should be tested before distribution (using "make disttest"),
and the tests should also be available to people installing the modules
(using "make test").
+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
development process or your time) include Test::Simple, Carp::Assert
and Test::Inline.
+For more sophisticated test suites there are Test::More and Test::MockObject.
=head2 Packaging
-Modules should be packaged using the standard MakeMaker tools, allowing
-them to be installed in a consistent manner. Use "make dist" to create
-your package.
-
-Tools exist to help you build your module in a MakeMaker-friendly style.
-These include ExtUtils::ModuleMaker and h2xs. See also L<perlnewmod>.
+Modules should be packaged using one of the standard packaging tools.
+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>.
=head2 Licensing
If you don't know what license to use, dual licensing under the GPL
and Artistic licenses (the same as Perl itself) is a good idea.
+See L<perlgpl> and L<perlartistic>.
=head1 COMMON PITFALLS
Verifies your POD's correctness
+=item Packaging Tools
+
+L<ExtUtils::MakeMaker>, L<Module::Build>
+
=item Testing tools
-L<Test::Simple>, L<Test::Inline>, L<Carp::Assert>
+L<Test::Simple>, L<Test::Inline>, L<Carp::Assert>, L<Test::More>, L<Test::MockObject>
=item http://pause.perl.org/
https://perl5.git.perl.org / perl5.git / blobdiff