Download pdf - What you need to remember when you upload to CPAN

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 Service

• CPAN Coverage report

• and (maybe) more...

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.

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

CPANTS

• http://cpants.cpanauthors.org/

• sees various aspects of a

distribution.

• sends no email (yet)

• provides rss feeds for each author.

CPAN::Changes

Kwalitee Service

• http://changes.cpanhq.org/

• sees the format of a Changes file.

• provides rss feeds for each

author/distribution.

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/entry/2010

• https://github.com/rjbs/misc/blob/master/code-review

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 hackathon)

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

• no_symlinks

• 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.

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_stdin_for_prompting

(optional)

• 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

(optional)

• metayml_declares_perl_version

(optional)

• metayml_has_provides (experimental)

• 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

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_license_file

(experimental)

• 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.

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 highest.

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 your friend.

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,

document it as well.

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)

• fits_fedora_license (experimental)

• 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-Toolchain-Gang?tab=members

http://qa-hackathon.org/reviews.html

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

distribution).

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

• https://github.com/cpants/www-cpants

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

Thank you