0
Perlのモジュールを公開するときに
気をつけておいた方がよい**個のこと
Kenichi Ishigaki
(@charsbar)
YAPC::Asia 2013
Sep 20, 2013
Have you ever
uploaded anything
to CPAN?
Part I
When you upload
a distribution...
An uploaded
distribution is
placed like this,
(CPAN root)/authors/id/P/PA/PAUSEID/Distribution-1.00.tar.gz
indexed if necessary,
mirrored,
(CPAN is the Comprehensive Perl Archive Network)
announced, tested,
and more ...
even if you try to
delete it.
What's done is
done and stays in
BackPAN.
PAUSE/CPAN also accepts
(almost) everything.
Be prepared
before you upload.
http://www.cpan.org/modules/04pause.html
Part II
CPAN Testing Services
There are several testing
services to improve CPAN.
• PAUSE (kind of)
• CPAN Testers
• CPANTS
• CPAN::Changes Kwalitee Ser...
PAUSE
• https://pause.perl.org/
• sees if a distribution extracts
nicely and is safe.
• authorizes packages.
• sends you e...
CPAN Testers
• http://www.cpantesters.org/
• gathers reports from testers under
various environments.
• sends you emails a...
CPANTS
• http://cpants.cpanauthors.org/
• sees various aspects of a
distribution.
• sends no email (yet)
• provides rss fe...
CPAN::Changes
Kwalitee Service
• http://changes.cpanhq.org/
• sees the format of a Changes file.
• provides rss feeds for ...
CPAN Coverage Report
• http://cpancover.com/
• sees the coverage of a distribution
(by Devel::Cover)
An example of making
use of them (by RJBS)
• http://rjbs.manxome.org/rubric/entry/2007
• http://rjbs.manxome.org/rubric/en...
Part III
Kwalitee in depth
There are 44 metrics.
• 30 core, 9 extra, and 5 experimental
(as of ver 0.91)
• 6 added, 12 removed
(at/after the QA hacka...
Many of them are
based on the past
toolchain issues.
http://weblog.bulknews.net/post/33907905561
http://cpants.cpanauthors.org/kwalitee/no_broken_module_install
http://cpants.cpanauthors.org/stats/module_install
http://weblog.bulknews.net/post/44251476706
http://cpants.cpanauthors.org/kwalitee/no_mymeta_files
We can't remember
everything.
Let CPANTS remember for the rest of us!
Metrics on availability
• extractable
• extracts_nicely
• no_pax_headers
• portable_filenames
• no_dot_underscore_files
• ...
• Use short, alphanumeric-only
names.
• Avoid links.
• COPYFILE_DISABLE=1 (Mac OS X)
• Use GNU tar.
• See if Archive::Tar ...
Metrics on integrity
• has_manifest
• manifest_mathces_dist
• valid_signature
• no_mymeta_files
• no_generated_files
• Update MANIFEST.SKIP if
exists.
• Update MANIFEST, or let
it be generated.
• Update .gitignore if
exists.
Metrics on file layout
• has_readme
• has_changelog
• has_tests
• has_tests_in_t_dir
(optional)
• proper_libs (optional)
• Use some generators.
• Minilla, Milla, Dist::Zilla
• pmsetup, Module::Setup
Metrics on build tool
• has_buildtool
• buildtool_not_executable
• no_broken_module_install
• no_broken_auto_install
• no_...
• Avoid Module::Install.
• Avoid prompting for smooth
installation.
• Release from non-Windows
environment if possible.
Metrics on META
• has_meta_yml
• metayml_is_parsable
• metayml_conforms_to_known_spec
• metayml_conforms_spec_current
(opt...
• Don't edit it by hand.
• META.yml and META.json may (often)
be generated differently.
• See specs when necessary.
http:/...
Stats on META generators
http://cpants.cpanauthors.org/stats/meta_generator
Stats on META generator users
Metrics on license
• has_human_readable_license
• has_license_in_source
• metayml_has_license
(optional)
• has_separate_li...
• Write explicitly (and machine-
readably if possible) about license.
• Adding a LICENSE file is a good idea.
(Fedora/Debi...
Metrics on versions
• has_version
• has_proper_version
• consistent_version
• package_version_matches_dist_version
• Don't remove versions
from packages (which
would cause version
downgrade).
• Bump up inconsistent
versions to the highes...
Metrics on prerequisites
• prereq_matches_use
• build_prereq_matches_use
(optional)
• is_prereq (optional)
• Don't take these metrics too
seriously (especially when
you do something clever).
• dynamic_config may (or
may not) be y...
Metrics on strictness
• use_strict
• use_warnings (optional)
• Just use them, or their
well-known equivalents
(like Moose and its
friends).
• If you want to do
something clever,
docum...
Metrics on pod
• no_pod_errors
• Update Pod::Simple to
find issues.
• Test::Pod and
Test::Pod::Coverage are
still your friends.
Metrics on repackaging
• easily_repackageable_by_debian
(experimental)
• easily_repackageable_by_fedora
(experimental)
• f...
• Nothing to remember.
These are not for you.
Too much to
remember?
The bottom line:
use better tools
• made by those who have a
good knowledge of the issues.
https://github.com/Perl-Toolcha...
Questions?
Thank you
bonus track
Part IV
Using CPANTS
Test::Kwalitee(::Extra)
• uses CPANTS analyzer
against local files
(though the analyzer is
made for a prepared
distributio...
Subscribing CPANTS Feeds
http://cpants.cpanauthors.org/author/ID/feed
Want raw data?
Add .json to urls.
(What's in JSON response may (often) change.)
Want status icons?
http://cpants.cpanauthors.org/author/ID.png
http://cpants.cpanauthors.org/dist/Name.png
Part V
When you find something is
broken or unimplemented
CPANTS repositories
• https://github.com/cpants/Module-CPANTS-Analyse
• https://github.com/cpants/Module-CPANTS-SiteKwalit...
Other related repositories
that may have a big impact.
• https://github.com/domm/Module-ExtractUse
• https://github.com/rj...
Thank you
Upcoming SlideShare
Loading in...5
×

What you need to remember when you upload to CPAN

375

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
375
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

Transcript of "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
  1. A particular slide catching your eye?

    Clipping is a handy way to collect important slides you want to go back to later.

×