=encoding utf8 =head1 NAME Release::Checklist - A QA checklist for CPAN releases =head1 Dependencies Only use default pragma's perl use 5.22.0; use strict; use feature "say"; use warnings; Do not add useless additional dependencies like L<sanity|https://metacpan.org/pod/sanity>, L<Modern::Perl|https://metacpan.org/pod/Modern::Perl>, common::sense, or L<nonsense|https://metacpan.org/pod/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. L<Test::Prereq|https://metacpan.org/pod/Test::Prereq> =head1 Test 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 t/ xt/ if possible, do not use L<Test::*|https://metacpan.org/search?q=Test%3A%3A&search_type=modules> 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 L<Test2::Harness|https://metacpan.org/pod/Test2::Harness> installed, also test with yath sh $ yath $ yath -j8 =head1 Documentation 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). L<Test::Pod|https://metacpan.org/pod/Test::Pod> L<Test::Pod::Coverage|https://metacpan.org/pod/Test::Pod::Coverage> =head1 Spelling 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. L<pod-spell-check|scripts/pod-spell-check> L<Pod::Aspell|https://metacpan.org/pod/Pod::Aspell> L<Pod::Escapes|https://metacpan.org/pod/Pod::Escapes> L<Pod::Parser|https://metacpan.org/pod/Pod::Parser> L<Pod::Spell|https://metacpan.org/pod/Pod::Spell> L<Pod::Spell::CommonMistakes|https://metacpan.org/pod/Pod::Spell::CommonMistakes> L<Pod::Wordlist|https://metacpan.org/pod/Pod::Wordlist> L<Text::Aspell|https://metacpan.org/pod/Text::Aspell> L<Text::Ispell|https://metacpan.org/pod/Text::Ispell> L<Text::Wrap|https://metacpan.org/pod/Text::Wrap> =head1 Examples 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. =head1 Test coverage Do not just test what you think would be used. There I<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. L<Devel::Cover|https://metacpan.org/pod/Devel::Cover> L<Test::TestCoverage|https://metacpan.org/pod/Test::TestCoverage> =head1 Version coverage 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 I<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 L<CPANTESTERS|http://www.cpantesters.org> can be a huge help. =head1 Minimal perl support 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 Do not guess. It is easy to check with L<Test::MinimumVersion|https://metacpan.org/pod/Test::MinimumVersion> and/or L<Test::MinimumVersion::Fast|https://metacpan.org/pod/Test::MinimumVersion::Fast>. L<Perl::MinimumVersion|https://metacpan.org/release/Perl-MinimumVersion> comes with the L<perlver|https://metacpan.org/pod/distribution/Perl-MinimumVersion/script/perlver> tool: ```shell $ perlver --blame test.pl ================================================================================ File : test.pl Line : 3 Char : 14 Rule : I<perl>5010_operators Version : 5.010 ================================================================================ // ================================================================================ ``` =head1 Multiple perl versions 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 L<Module::Release|https://metacpan.org/pod/Module::Release> L<.releaserc|./.releaserc> 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; With -Uuselongdouble: ok 1 1..1 with -Duselongdouble 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. =head1 XS If you use XS, make sure you (try to) support the widest range of perl versions. L<Devel::PPPort|https://metacpan.org/pod/Devel::PPPort> (most recent version) =head1 Leak tests L<Test::LeakTrace::Script|https://metacpan.org/pod/Test::LeakTrace::Script> L<Test::Valgrind|https://metacpan.org/pod/Test::Valgrind> L<valgrind|http://valgrind.org> =head1 Release archive Some see L<CPANTS|http://cpants.perl.org/> 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. L<Test::Package|....> L<Test::Kwalitee|https://metacpan.org/pod/Test::Kwalitee> L<Module::CPANTS::Analyse|https://metacpan.org/pod/Module::CPANTS::Analyse> L<cpants_lint.pl|https://metacpan.org/pod/distribution/App-CPANTS-Lint/bin/cpants_lint.pl> 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! $ =head1 Clean dist 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. L<MANIFEST|./MANIFEST> and L<MANIFEST.skip|MANIFEST.skip> are complete sh $ make dist $ make distclean L<Test::Manifest|https://metacpan.org/pod/Test::Manifest> L<Test::DistManifest|https://metacpan.org/pod/Test::DistManifest> =head1 Code style consistency Add a L<CONTRIBUTING.md|./CONTRIBUTING.md> or similar file to guide others to consistency that will match L<I<your> style|http://tux.nl/style.html> (or, in case of joint effort, the style as agreed upon by the developers). 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. L<Perl::Tidy|https://metacpan.org/pod/Perl::Tidy> L<Perl::Critic|https://metacpan.org/pod/Perl::Critic> + L<plugins|https://metacpan.org/search?q=Perl%3A%3ACritic%3A%3A&search_type=modules>, lot of choices L<Test::Perl::Critic|https://metacpan.org/pod/Test::Perl::Critic> L<Test::Perl::Critic::Policy|https://metacpan.org/pod/Test::Perl::Critic::Policy> L<Test::TrailingSpace|https://metacpan.org/pod/Test::TrailingSpace> L<Perl::Lint|https://metacpan.org/pod/Perl::Lint> L<.perltidy|./.perltidyrc> and L<.perlcritic|./.perlcriticrc>. =head1 META 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 L<META spec 1.4 (2008)|http://module-build.sourceforge.net/META-spec-v1.4.html> or L<META spec 2.0 (2011)|http://module-build.sourceforge.net/META-spec-v2.0.html>: L<CPAN::Meta::Converter|https://metacpan.org/pod/CPAN::Meta::Converter> L<CPAN::Meta::Validator|https://metacpan.org/pod/CPAN::Meta::Validator> L<JSON::PP|https://metacpan.org/pod/JSON::PP> L<Parse::CPAN::Meta|https://metacpan.org/pod/Parse::CPAN::Meta> L<Test::CPAN::Meta::JSON|https://metacpan.org/pod/Test::CPAN::Meta::JSON> L<Test::CPAN::Meta::YAML|https://metacpan.org/pod/Test::CPAN::Meta::YAML> L<Test::CPAN::Meta::YAML::Version|https://metacpan.org/pod/Test::CPAN::Meta::YAML::Version> L<YAML::Syck|https://metacpan.org/pod/YAML::Syck> =head1 Versions 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. L<Test::Version|https://metacpan.org/pod/Test::Version> Make sure it is a versioning system that increments L<Test::GreaterVersion|https://metacpan.org/pod/Test::GreaterVersion> =head1 Changelog Make sure your L<ChangeLog|./ChangeLog> or Changes file is up-to-date. Your release procedure might check the most recent mentioned date in that L<Date::Calc|https://metacpan.org/pod/Date::Calc> L<Test::CPAN::Changes|https://metacpan.org/pod/Test::CPAN::Changes> =head1 Performance Check if your release matches previous performance =over =item - between different versions of perl =item - between different versions of the module =item - between different versions of dependencies =back =head1 License 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. =head1 README / README.md Add a L<file|./README.md> the states in short the purpose of your distribution. Make sure your SYNOPSIS section in the pod makes sense L<Test::Synopsis|https://metacpan.org/pod/Test::Synopsis> L<Text::Markdown|https://metacpan.org/pod/Text::Markdown> =head1 Downriver 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. L<used_by.pl|scripts/used-by.pl> will check the depending modules with the upcoming version. =head1 LICENSE 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.