What you need to remember when you upload to CPAN

466
-1

Published on

presented at YAPC::Asia 2013

Published in: Technology, Art & Photos
0 Comments
1 Like
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total Views
466
On Slideshare
0
From Embeds
0
Number of Embeds
3
Actions
Shares
0
Downloads
1
Comments
0
Likes
1
Embeds 0
No embeds

No notes for slide

What you need to remember when you upload to CPAN

  1. 1. Perlのモジュールを公開するときに 気をつけておいた方がよい**個のこと Kenichi Ishigaki (@charsbar) YAPC::Asia 2013 Sep 20, 2013
  2. 2. Have you ever uploaded anything to CPAN?
  3. 3. Part I When you upload a distribution...
  4. 4. An uploaded distribution is placed like this, (CPAN root)/authors/id/P/PA/PAUSEID/Distribution-1.00.tar.gz
  5. 5. indexed if necessary,
  6. 6. mirrored, (CPAN is the Comprehensive Perl Archive Network)
  7. 7. announced, tested, and more ...
  8. 8. even if you try to delete it.
  9. 9. What's done is done and stays in BackPAN.
  10. 10. PAUSE/CPAN also accepts (almost) everything.
  11. 11. Be prepared before you upload. http://www.cpan.org/modules/04pause.html
  12. 12. Part II CPAN Testing Services
  13. 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. 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. 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. 16. CPANTS • http://cpants.cpanauthors.org/ • sees various aspects of a distribution. • sends no email (yet) • provides rss feeds for each author.
  17. 17. CPAN::Changes Kwalitee Service • http://changes.cpanhq.org/ • sees the format of a Changes file. • provides rss feeds for each author/distribution.
  18. 18. CPAN Coverage Report • http://cpancover.com/ • sees the coverage of a distribution (by Devel::Cover)
  19. 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. 20. Part III Kwalitee in depth
  21. 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. 22. Many of them are based on the past toolchain issues.
  23. 23. http://weblog.bulknews.net/post/33907905561
  24. 24. http://cpants.cpanauthors.org/kwalitee/no_broken_module_install
  25. 25. http://cpants.cpanauthors.org/stats/module_install
  26. 26. http://weblog.bulknews.net/post/44251476706
  27. 27. http://cpants.cpanauthors.org/kwalitee/no_mymeta_files
  28. 28. We can't remember everything. Let CPANTS remember for the rest of us!
  29. 29. Metrics on availability • extractable • extracts_nicely • no_pax_headers • portable_filenames • no_dot_underscore_files • no_symlinks
  30. 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. 31. Metrics on integrity • has_manifest • manifest_mathces_dist • valid_signature • no_mymeta_files • no_generated_files
  32. 32. • Update MANIFEST.SKIP if exists. • Update MANIFEST, or let it be generated. • Update .gitignore if exists.
  33. 33. Metrics on file layout • has_readme • has_changelog • has_tests • has_tests_in_t_dir (optional) • proper_libs (optional)
  34. 34. • Use some generators. • Minilla, Milla, Dist::Zilla • pmsetup, Module::Setup
  35. 35. Metrics on build tool • has_buildtool • buildtool_not_executable • no_broken_module_install • no_broken_auto_install • no_stdin_for_prompting (optional)
  36. 36. • Avoid Module::Install. • Avoid prompting for smooth installation. • Release from non-Windows environment if possible.
  37. 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. 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. 39. Stats on META generators http://cpants.cpanauthors.org/stats/meta_generator
  40. 40. Stats on META generator users
  41. 41. Metrics on license • has_human_readable_license • has_license_in_source • metayml_has_license (optional) • has_separate_license_file (experimental)
  42. 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. 43. Metrics on versions • has_version • has_proper_version • consistent_version • package_version_matches_dist_version
  44. 44. • Don't remove versions from packages (which would cause version downgrade). • Bump up inconsistent versions to the highest.
  45. 45. Metrics on prerequisites • prereq_matches_use • build_prereq_matches_use (optional) • is_prereq (optional)
  46. 46. • Don't take these metrics too seriously (especially when you do something clever). • dynamic_config may (or may not) be your friend.
  47. 47. Metrics on strictness • use_strict • use_warnings (optional)
  48. 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. 49. Metrics on pod • no_pod_errors
  50. 50. • Update Pod::Simple to find issues. • Test::Pod and Test::Pod::Coverage are still your friends.
  51. 51. Metrics on repackaging • easily_repackageable_by_debian (experimental) • easily_repackageable_by_fedora (experimental) • fits_fedora_license (experimental)
  52. 52. • Nothing to remember. These are not for you.
  53. 53. Too much to remember?
  54. 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. 55. Questions?
  56. 56. Thank you
  57. 57. bonus track
  58. 58. Part IV Using CPANTS
  59. 59. Test::Kwalitee(::Extra) • uses CPANTS analyzer against local files (though the analyzer is made for a prepared distribution).
  60. 60. Subscribing CPANTS Feeds http://cpants.cpanauthors.org/author/ID/feed
  61. 61. Want raw data? Add .json to urls. (What's in JSON response may (often) change.)
  62. 62. Want status icons? http://cpants.cpanauthors.org/author/ID.png http://cpants.cpanauthors.org/dist/Name.png
  63. 63. Part V When you find something is broken or unimplemented
  64. 64. CPANTS repositories • https://github.com/cpants/Module-CPANTS-Analyse • https://github.com/cpants/Module-CPANTS-SiteKwalitee • https://github.com/cpants/www-cpants
  65. 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. 66. Thank you

×