Kwalitee

What's "Kwalitee", anyway?

I'll hand the micropohone over to Schwern (or rather: I'll copy'n'paste from his old CPANTS slides):

  What is a good module? That's hard to say.
  
  What is good code? That's also hard to say.
  
  "Quality" is not a well-defined term in computing ... and especially not Perl.

  One man's Thing of Beauty is another's man's Evil Hack
  
  Since we can't define quality, how do we write a program to assure it?

Schwern decided to cleverly avoid this problem by not testing for quality but for Kwalitee: It looks like quality, it sounds like quality, but it's not quite quality.

Kwalitee Indicators Overview

Available Kwalitee: 23 (including optional metrics: 32)

If you want to discuss Kwalitee indicators or suggest new ones, please use the perl-qa list.

Core Indicators

Optional Indicators

has_example
has_test_pod
has_test_pod_coverage
has_tests_in_t_dir
is_prereq
metayml_conforms_spec_current
no_stdin_for_prompting
prereq_matches_use
use_warnings

Kwalitee Indicators

Core Indicators

buildtool_not_executable: Shortcoming: The buildtool (Build.PL/Makefile.PL) is executable. This is bad, because you should specifiy which perl you want to use while installing.
Remedy: Change the permissions of Build.PL/Makefile.PL to not-executable.
Defined in: Module::CPANTS::Kwalitee::Files
Show complying dists | Show failing dists
extractable: Shortcoming: This package uses an unknown packaging format. CPANTS can handle tar.gz, tgz and zip archives. No kwalitee metrics have been calculated.
Remedy: Pack the distribution with tar & gzip or zip.
Defined in: Module::CPANTS::Kwalitee::Files
Show complying dists | Show failing dists
extracts_nicely: Shortcoming: This package doesn't create a directory and extracts its content into this directory. Instead, it spews its content into the current directory, making it really hard/annoying to remove the unpacked package.
Remedy: Issue the command to pack the distribution in the directory above it. Or use a buildtool ('make dist' or 'Build dist')
Defined in: Module::CPANTS::Kwalitee::Files
Show complying dists | Show failing dists
has_buildtool: Shortcoming: Makefile.PL and/or Build.PL are missing. This makes installing this distribution hard for humans and impossible for automated tools like CPAN/CPANPLUS
Remedy: Use a buildtool like Module::Build (recomended) or ExtUtils::MakeMaker to manage your distribution
Defined in: Module::CPANTS::Kwalitee::Files
Show complying dists | Show failing dists
has_changelog: Shortcoming: The distribution hasn't got a Changelog (named something like m/^chang(es?|log)|history$/i. A Changelog helps people decide if they want to upgrade to a new version.
Remedy: Add a Changelog (best named 'Changes') to the distribution. It should list at least major changes implemented in newer versions.
Defined in: Module::CPANTS::Kwalitee::Files
Show complying dists | Show failing dists
has_humanreadable_license: Shortcoming: This distribution does not have a license defined in the documentation or in a file called LICENSE
Remedy: Add a section called 'LICENSE' to the documentation, or add a file named LICENSE to the distribution.
Defined in: Module::CPANTS::Kwalitee::License
Show complying dists | Show failing dists
has_manifest: Shortcoming: The file 'MANIFEST' is missing from this distribution. The MANIFEST lists all files included in the distribution.
Remedy: Add a MANIFEST to the distribution. Your buildtool should be able to autogenerate it (eg 'make manifest' or './Build manifest')
Defined in: Module::CPANTS::Kwalitee::Files
Show complying dists | Show failing dists
has_meta_yml: Shortcoming: The file 'META.yml' is missing from this distribution. META.yml is needed by people maintaining module collections (like CPAN), for people writing installation tools, or just people who want to know some stuff about a distribution before downloading it.
Remedy: Add a META.yml to the distribution. Your buildtool should be able to autogenerate it.
Defined in: Module::CPANTS::Kwalitee::Files
Show complying dists | Show failing dists
has_proper_version: Shortcoming: The version number isn't a number. It probably contains letter besides a leading 'v', which it shouldn't
Remedy: Remove all letters from the version number. If you want to mark a release as a developer release, use the scheme 'Module-1.00_01'
Defined in: Module::CPANTS::Kwalitee::Distname
Show complying dists | Show failing dists
has_readme: Shortcoming: The file 'README' is missing from this distribution. The README provide some basic information to users prior to downloading and unpacking the distribution.
Remedy: Add a README to the distribution. It should contain a quick description of your module and how to install it.
Defined in: Module::CPANTS::Kwalitee::Files
Show complying dists | Show failing dists
has_tests: Shortcoming: This distribution doesn't contain either a file called 'test.pl' or a directory called 't'. This indicates that it doesn't contain even the most basic test-suite. This is really BAD!
Remedy: Add tests!
Defined in: Module::CPANTS::Kwalitee::Files
Show complying dists | Show failing dists
has_version: Shortcoming: The package filename (eg. Foo-Bar-1.42.tar.gz) does not include a version number (or something that looks like a reasonable version number to CPAN::DistnameInfo)
Remedy: Add a version number to the packed distribution. Or use a buildtool ('make dist' or 'Build dist')
Defined in: Module::CPANTS::Kwalitee::Distname
Show complying dists | Show failing dists
has_working_buildtool: Shortcoming: This package uses an obsolete version of Module::Install. Versions of Module::Install prior to 0.61 might not work on some systems at all. Additionally if your Makefile.PL uses the 'auto_install()' feature, you need at least version 0.64.
Remedy: Upgrade the bundled version of Module::Install to at least 0.61, but preferably to the most current release. Alternatively, you can switch to another build system / installer that does not suffer from this problem. (ExtUtils::MakeMaker, Module::Build both of which have their own set of problems.)
Defined in: Module::CPANTS::Kwalitee::BrokenInstaller
Show complying dists | Show failing dists
manifest_matches_dist: Shortcoming: MANIFEST does not match the contents of this distribution. See 'error_manifest_matches_dist' in the dist view for more info.
Remedy: Use a buildtool to generate the MANIFEST. Or update MANIFEST manually.
Defined in: Module::CPANTS::Kwalitee::Manifest
Show complying dists | Show failing dists
metayml_conforms_to_known_spec: Shortcoming: META.yml does not conform to any recognised META.yml Spec. See 'metayml' in the dist error view for more info.
Remedy: Take a look at the META.yml Spec at http://module-build.sourceforge.net/META-spec-current.html and change your META.yml accordingly
Defined in: Module::CPANTS::Kwalitee::MetaYML
Show complying dists | Show failing dists
metayml_has_license: Shortcoming: This distribution does not have a license defined in META.yml.
Remedy: Define the license if you are using in Build.PL. If you are using MakeMaker (Makefile.PL) you should upgrade to ExtUtils::MakeMaker version 6.31.
Defined in: Module::CPANTS::Kwalitee::MetaYML
Show complying dists | Show failing dists
metayml_is_parsable: Shortcoming: The META.yml file of this distributioncould not be parsed by the version of YAML.pm CPANTS is using.
Remedy: If you don't have one, add a META.yml file. Else, upgrade your YAML generator so it produces valid YAML.
Defined in: Module::CPANTS::Kwalitee::MetaYML
Show complying dists | Show failing dists
no_cpants_errors: Shortcoming: Some errors occured during CPANTS testing. They might be caused by bugs in CPANTS or some strange features of this distribution. See 'cpants' in the dist error view for more info.
Remedy: Please report the error(s) to bug-module-cpants-analyse@rt.cpan.org
Defined in: Module::CPANTS::Kwalitee::CpantsErrors
Show complying dists | Show failing dists
no_generated_files: Shortcoming: This distribution has a file that it should generate and not be distribute.
Remedy: Remove the offending file!
Defined in: Module::CPANTS::Kwalitee::Files
Show complying dists | Show failing dists
no_pod_errors: Shortcoming: The documentation for this distribution contains syntactic errors in its POD. Note that this metric tests all .pl, .pm and .pod files, even if they are in t/. See 'pod_message' in the dist error view for more info.
Remedy: Remove the POD errors. You can check for POD errors automatically by including Test::Pod to your test suite.
Defined in: Module::CPANTS::Kwalitee::Pod
Show complying dists | Show failing dists
no_symlinks: Shortcoming: This distribution includes symbolic links (symlinks). This is bad, because there are operating systems that do not handle symlinks.
Remedy: Remove the symlinkes from the distribution.
Defined in: Module::CPANTS::Kwalitee::Files
Show complying dists | Show failing dists
proper_libs: Shortcoming: There is more than one .pm file in the base dir, or the .pm files are not in directory lib.
Remedy: Move your *.pm files in a directory named 'lib'. The directory structure should look like 'lib/Your/Module.pm' for a module named 'Your::Module'.
Defined in: Module::CPANTS::Kwalitee::FindModules
Show complying dists | Show failing dists
use_strict: Shortcoming: This distribution does not 'use strict;' in all of its modules.
Remedy: Add 'use strict' to all modules.
Defined in: Module::CPANTS::Kwalitee::Uses
Show complying dists | Show failing dists

Optional Indicators

has_example: Shortcoming: This distribution does not include examples.
Remedy: Add a directory matching the regex (bin|scripts?|ex|eg|examples?|samples?|demos?) or a file matching the regex /\/(examples?|samples?|demos?)\.p(m|od)$/i to your distribution that includes some scripts showing one or more use-cases of the distribution.
Defined in: Module::CPANTS::Kwalitee::Files
Show complying dists | Show failing dists
has_test_pod: Shortcoming: Doesn't include a test for pod correctness (Test::Pod)
Remedy: Add a test using Test::Pod to check for pod correctness.
Defined in: Module::CPANTS::Kwalitee::Uses
Show complying dists | Show failing dists
has_test_pod_coverage: Shortcoming: Doesn't include a test for pod coverage (Test::Pod::Coverage)
Remedy: Add a test using Test::Pod::Coverage to check for POD coverage.
Defined in: Module::CPANTS::Kwalitee::Uses
Show complying dists | Show failing dists
has_tests_in_t_dir: Shortcoming: This distribution contains either a file called 'test.pl' (the old test file) or is missing a directory called 't'. This indicates that it uses the old test mechanism or it has no test-suite.
Remedy: Add tests or move tests.pl to the t/ directory!
Defined in: Module::CPANTS::Kwalitee::Files
Show complying dists | Show failing dists
is_prereq: Shortcoming: This distribution is not required by another distribution by another author.
Remedy: Convince / force / bribe another CPAN author to use this distribution.
Defined in: Module::CPANTS::Kwalitee::Prereq
Show complying dists | Show failing dists
metayml_conforms_spec_current: Shortcoming: META.yml does not conform to the Current META.yml Spec (1.4). See 'metayml' in the dist error view for more info.
Remedy: Take a look at the META.yml Spec at http://module-build.sourceforge.net/META-spec-current.html and change your META.yml accordingly
Defined in: Module::CPANTS::Kwalitee::MetaYML
Show complying dists | Show failing dists
no_stdin_for_prompting: Shortcoming: This distribution is using direct call from STDIN instead of prompt())
Remedy: Use the prompt() method
Defined in: Module::CPANTS::Kwalitee::Files
Show complying dists | Show failing dists
prereq_matches_use: Shortcoming: This distribution uses a module or a dist that's not listed as a prerequisite.
Remedy: List all used modules in META.yml requires
Defined in: Module::CPANTS::Kwalitee::Prereq
Show complying dists | Show failing dists
use_warnings: Shortcoming: This distribution does not 'use warnings;' in all of its modules.
Remedy: Add 'use warnings' to all modules. (This will require perl > 5.6)
Defined in: Module::CPANTS::Kwalitee::Uses
Show complying dists | Show failing dists