What you need to remember when you upload to CPAN

  • View

  • Download

Embed Size (px)


presented at YAPC::Asia 2013


  • 1. Perl ** Kenichi Ishigaki (@charsbar) YAPC::Asia 2013 Sep 20, 2013

2. Have you ever uploaded anything to CPAN? 3. Part I When you upload a distribution... 4. An uploaded distribution is placed like this, (CPAN root)/authors/id/P/PA/PAUSEID/Distribution-1.00.tar.gz 5. indexed if necessary, 6. mirrored, (CPAN is the Comprehensive Perl Archive Network) 7. announced, tested, and more ... 8. even if you try to delete it. 9. What's done is done and stays in BackPAN. 10. PAUSE/CPAN also accepts (almost) everything. 11. Be prepared before you upload. http://www.cpan.org/modules/04pause.html 12. Part II CPAN Testing Services 13. There are several testing services to improve CPAN. PAUSE (kind of) CPAN Testers CPANTS CPAN::Changes Kwalitee Service CPAN Coverage report and (maybe) more... 14. PAUSE https://pause.perl.org/ sees if a distribution extracts nicely and is safe. authorizes packages. sends you emails when packages are indexed or errors are found. 15. CPAN Testers http://www.cpantesters.org/ gathers reports from testers under various environments. sends you emails about fail reports (if requested). provides rss feeds for each author/distribution. welcomes donation: https://members.enlightenedperl.org/ drupal/donate-cpan-testers 16. CPANTS http://cpants.cpanauthors.org/ sees various aspects of a distribution. sends no email (yet) provides rss feeds for each author. 17. CPAN::Changes Kwalitee Service http://changes.cpanhq.org/ sees the format of a Changes file. provides rss feeds for each author/distribution. 18. CPAN Coverage Report http://cpancover.com/ sees the coverage of a distribution (by Devel::Cover) 19. An example of making use of them (by RJBS) http://rjbs.manxome.org/rubric/entry/2007 http://rjbs.manxome.org/rubric/entry/2010 https://github.com/rjbs/misc/blob/master/code-review 20. Part III Kwalitee in depth 21. There are 44 metrics. 30 core, 9 extra, and 5 experimental (as of ver 0.91) 6 added, 12 removed (at/after the QA hackathon) 22. Many of them are based on the past toolchain issues. 23. http://weblog.bulknews.net/post/33907905561 24. http://cpants.cpanauthors.org/kwalitee/no_broken_module_install 25. http://cpants.cpanauthors.org/stats/module_install 26. http://weblog.bulknews.net/post/44251476706 27. http://cpants.cpanauthors.org/kwalitee/no_mymeta_files 28. We can't remember everything. Let CPANTS remember for the rest of us! 29. Metrics on availability extractable extracts_nicely no_pax_headers portable_filenames no_dot_underscore_files no_symlinks 30. Use short, alphanumeric-only names. Avoid links. COPYFILE_DISABLE=1 (Mac OS X) Use GNU tar. See if Archive::Tar (ptar) can extract your distribution. 31. Metrics on integrity has_manifest manifest_mathces_dist valid_signature no_mymeta_files no_generated_files 32. Update MANIFEST.SKIP if exists. Update MANIFEST, or let it be generated. Update .gitignore if exists. 33. Metrics on file layout has_readme has_changelog has_tests has_tests_in_t_dir (optional) proper_libs (optional) 34. Use some generators. Minilla, Milla, Dist::Zilla pmsetup, Module::Setup 35. Metrics on build tool has_buildtool buildtool_not_executable no_broken_module_install no_broken_auto_install no_stdin_for_prompting (optional) 36. Avoid Module::Install. Avoid prompting for smooth installation. Release from non-Windows environment if possible. 37. Metrics on META has_meta_yml metayml_is_parsable metayml_conforms_to_known_spec metayml_conforms_spec_current (optional) metayml_declares_perl_version (optional) metayml_has_provides (experimental) 38. Don't edit it by hand. META.yml and META.json may (often) be generated differently. See specs when necessary. http://module-build.sourceforge.net/META-spec-v1.4.html http://search.cpan.org/perldoc?CPAN::Meta::Spec 39. Stats on META generators http://cpants.cpanauthors.org/stats/meta_generator 40. Stats on META generator users 41. Metrics on license has_human_readable_license has_license_in_source metayml_has_license (optional) has_separate_license_file (experimental) 42. Write explicitly (and machine- readably if possible) about license. Adding a LICENSE file is a good idea. (Fedora/Debian package managers would like you.) You still need to tweak WriteMakefile to support perl < 5.8.9. 43. Metrics on versions has_version has_proper_version consistent_version package_version_matches_dist_version 44. Don't remove versions from packages (which would cause version downgrade). Bump up inconsistent versions to the highest. 45. Metrics on prerequisites prereq_matches_use build_prereq_matches_use (optional) is_prereq (optional) 46. Don't take these metrics too seriously (especially when you do something clever). dynamic_config may (or may not) be your friend. 47. Metrics on strictness use_strict use_warnings (optional) 48. Just use them, or their well-known equivalents (like Moose and its friends). If you want to do something clever, document it as well. 49. Metrics on pod no_pod_errors 50. Update Pod::Simple to find issues. Test::Pod and Test::Pod::Coverage are still your friends. 51. Metrics on repackaging easily_repackageable_by_debian (experimental) easily_repackageable_by_fedora (experimental) fits_fedora_license (experimental) 52. Nothing to remember. These are not for you. 53. Too much to remember? 54. The bottom line: use better tools made by those who have a good knowledge of the issues. https://github.com/Perl-Toolchain-Gang?tab=members http://qa-hackathon.org/reviews.html 55. Questions? 56. Thank you 57. bonus track 58. Part IV Using CPANTS 59. Test::Kwalitee(::Extra) uses CPANTS analyzer against local files (though the analyzer is made for a prepared distribution). 60. Subscribing CPANTS Feeds http://cpants.cpanauthors.org/author/ID/feed 61. Want raw data? Add .json to urls. (What's in JSON response may (often) change.) 62. Want status icons? http://cpants.cpanauthors.org/author/ID.png http://cpants.cpanauthors.org/dist/Name.png 63. Part V When you find something is broken or unimplemented 64. CPANTS repositories https://github.com/cpants/Module-CPANTS-Analyse https://github.com/cpants/Module-CPANTS-SiteKwalitee https://github.com/cpants/www-cpants 65. Other related repositories that may have a big impact. https://github.com/domm/Module-ExtractUse https://github.com/rjbs/Software-License https://github.com/Perl-Toolchain-Gang/CPAN-Meta https://github.com/charsbar/Parse-PMFile 66. Thank you