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