- Test coverage
- Version coverage
- Minimal perl support
- Multiple perl versions
- Leak tests
- Release archive
- Clean dist
- Code style consistency
- README / README.md
Release::Checklist - A QA checklist for CPAN releases
Only use default pragma's
perl use 5.22.0; use strict; use feature "say"; use warnings;
Do not add useless additional dependencies like sanity, Modern::Perl, common::sense, or nonsense. However useful they might be in your own working environment and force you into behaving well, adding them as a requirement to a CPAN module will increase the complexity of the requirements to probably no good use, as they are unlikely to be found on all your targeted systems and add a chance to break.
There is no problem with you using those in your own (non-CPAN) scripts and modules, but please do not add needless dependencies.
Test, test and test. The more you test, the lower the chance you will break your code with small changes.
perl use strict; use warnings; use Test::More; : done_testing ();
Separate your module tests and your author tests
if possible, do not use Test::* modules that you do not actually require, however fancy they may be. See the point about dependencies.
If you are still using any additional Test:: module, do not mix your own code with the functionality from a/the module. Be consistent: use all or use nothing. That is: if the module you (now) use comes with features you had scripted yourself before using that module, replace them too.
If adding tests after a bug-fix, add at least two tests: one that tests that the required (fixed) behavior now passes and that the invalid behavior fails.
Check to see if your tests support running in parallel sh $ prove -vwb -j8
If you have Test2::Harness installed, also test with yath sh $ yath $ yath -j8
Make sure that you have a clear SYNOPSIS section. This section should show the most important code as simple and clear as possible. If you have 3500 methods in your class, do not list all of the there. Just show how to create the object and show the 4 methods that a beginner would use.
Make sure your documentation is complete and all your methods and/or functions are documented. If you have private functions, mentions that in the documentation, so users can read that they might disappear without warning.
Make sure your pod is correct and can also be parsed by the pod-modules in the lowest version of perl you support (or mention that you need at least version whatever to read the pod as intended).
Not every developer is of native English tongue. And even if, they also make (spelling) mistakes. There are enough tools available to prevent public display of misspellings and typoes. Use them.
It is a good plan to have someone else proofread your documentation. If you can, ask three readers: one who knows about what the module is about, one who can be seen as an end-user of this modules without any knowledge about the internals, and last someone who has no clue about programming. You might be surprised of what they will find in the documentation as weird, unclear, or even plain wrong.
Have examples of your code. Preferably both in the EXAMPLES section of the pod, as in a folder names examples.
It is good practice to use your example code/scripts in your documentation too, as that gives you a two-way check (additional to your tests). Even better if the test scripts can be used as examples.
Do not just test what you think would be used. There will be users that try to bend the rules and invent ways for your module to be useful that you would never think of.
If every line of your code is tested, not only do you prevent unexpected breakage, but you also make sure that most corner cases are tested. Besides that, it will probably confront your with questions like "What can I possibly do to get into this part of my code?". Which may cause optimizations and other fun.
This is a hard one. If your release/dist requires specific versions of other modules, try to create an environment where you test your distribution against the required version and a version that does not meet the minimum version.
If your module requires Foo::Bar-0.123 because it supports correct UTF-8 encoding/decoding, and you wrote a test for that, your release is apt to fail in an environment where Foo::Bar-0.023 is installed.
This gets really hard to set up if your release has different code for versions of perl and for versions of required modules, but it pays off eventually. Note that monitoring CPANTESTERS can be a huge help.
Your Makefile.PL (or whatever build system you use) will have to state a minimal supported perl version that ends up in META.json and META.yml
================================================================================ File : test.pl Line : 3 Char : 14 Rule : perl5010_operators Version : 5.010
If you have multiple perls installed on your system, test your module or release with all of them before doing the release. Best would be to test with a threaded perl and a non-threaded perl. If you can test with a mixture of -Duselongdouble and 32bit/64bit perls, that would be even better.
$ perl -wc lib/Foo/Bar.pm
Repeat this on as many architectures as you can (i586, x64, IA64, PA-RISC, Sparc, PowerPC, …)
Repeat this on as many Operating Systems as you can (Linux, NetBSD, OSX, HP-UX, Solaris, Windows, OpenVMS, AIX, …)
Testing against a -Duselongdouble compiled perl will surface bad tests, e.g. tests that match against NVs like 2.1: perl use Test::More; my $i = 21000000000000001; $i /= 10e15; is ($i, 2.1); done_testing;
ok 1 1..1
not ok 1 # Failed test at -e line 1. # got: '2.1000000000000001' # expected: '2.1' 1..1 # Looks like you failed 1 test of 1.
If you use XS, make sure you (try to) support the widest range of perl versions.
Devel::PPPort (most recent version)
Some see CPANTS as a game, but many of the tests it puts on your release have a reason. Before you upload, you can check most of that to prevent unhappy users.
sh $ perl Makefile.PL $ make test $ make dist $ cpants_lint.pl Foo-Bar-0.01.tar.gz Checked dist: Foo-Bar-0.01.tar.gz Score: 144.44% (26/18) Congratulations for building a 'perfect' distribution! $
Some problems only surface when you do a make clean or make distclean. The develop cycle normally only adds and changes files, and if you forget to add those to the MANIFEST, your distribution will be incomplete and is likely to fail on other systems, whereas your tests locally still keep passing.
sh $ make dist $ make distclean
There are helper modules to enforce a style (given a configuration) or to try to help contributors to come up with a path/change than matches the project's style and layout. Again: consistency helps. A lot.
Make sure your meta-data matches the expected requirements. That can be achieved by using a generator that produces conform the most recent specifications or by using tools to check handcrafted META-files against the META spec 1.4 (2008) or META spec 2.0 (2011):
Use a sane versioning system that the rest of the world might understand. Do not use the MD5 of the current date and time related to the phase of the moon or versions that include quotes or spaces. Keep it simple and clear.
Make sure it is a versioning system that increments
Make sure your ChangeLog or Changes file is up-to-date. Your release procedure might check the most recent mentioned date in that
Check if your release matches previous performance
between different versions of perl
between different versions of the module
between different versions of dependencies
Make a clear statement about your license. (or choose a default, but at least state it).
Some target areas require a license in order to allow a CPAN module to be installed.
Add a file the states in short the purpose of your distribution.
Make sure your SYNOPSIS section in the pod makes sense
You have had reasons to make the changes leading up to a new distribution. If you really care about the users of your module, you should check if your new release would break any of the CPAN modules that (indirectly) depend on your module by testing with your previous release and your upcoming release and see if the new release would cause the other module to break.
used_by.pl will check the depending modules with the upcoming version.
Copyright (C) 2015-2018 H.Merijn Brand. All rights reserved.
This library is free software; you can redistribute and/or modify it under the same terms as Perl itself.