These are a list of things Debian needs in order to package your Perl distributions quickly and easily. I'm not sure whether this should be considered more of a wishlist or a checklist, but these are the things that most commonly stall us from integrating modules.
- Provide adequate copyright/license information
- By far the most common thing holding back many modules; Debian is particularly picky about this, but it's useful information to have for yourself as well, to make sure the team understands the terms of contribution (ie, who gets to keep copyright), etc
Use Debian Free Software Guideline-approved licenses wherever possible (otherwise, they end up in the 'nonfree' section of the archive
- Including convenience copies like RFCs is bad because they are non-free, so we have to either repackage your distribution without it, or put your distribution in the nonfree section of the archive
- Provide complete copyright and license details, covering all files (for Debian, we assume binary files may have different copyright/license terms, so if you are distributing JPEGs or similar, be explicit that the "same as Perl" terms still apply to those, and that you are the creator/copyright holder of the files)
"Public Domain" is technically not a Debian-free license, so if you decide to license Public Domain software, things get a bit trickier. You can look at some recommendations for choosing an appropriate license, but generally Artistic or GPL-1+ (same terms as the perl interpreter itself) is the de-facto choice within Perl.
- Specify things like:
- If copyright holders have not been historically known, or many people worked on a package, it's best to consider each author a copyright holder (per the Berne Convention)
- Matt S. Trout has a script called copyrite-gen that helps with this
- More copyright holders = more work for Debian, as things are tracked individually
- A COPYRIGHT.yml (or, probably better yet, something as part of META.yml/META.json for copyright information would be nice, so we can autogenerate copyright information
- A metadata file that can be used to generate copyright clauses for POD would be nice, rather than vice-versa
- Maybe a specific POD format can be used for this, but POD is sort of painful to parse
- For new projects or where there are few copyright holders, try to assign copyright either to a company or to a few key individuals, so that future decisions can be made (ie, in case people wish to relicense the software, or make other such decisions that require copyright holders to acquiesce)
For copyright to a company, you must make sure it is a legal entity -- that is, a registered corporation. Otherwise it cannot hold copyright; so something like "Some Module Developer Team" doesn't work (though "respective authors on Some Developer Module Team" would work)
- Provide some indication of whether dependencies are
- Fully required: stuff will break without this (usually in requires in META.yml)
Recommended: most users will want this installed along with the software, but it's not strictly needed (nothing will break without it, including tests; modules like Test::Without::Module may be beneficial here)
- Optional: some users may choose to use these, but a user installing the software wouldn't necessarily expect this to be installed alongside it. In Debian we call this "Suggests"
- The key here is to make sure you don't specify things are required that are actually recommendations, or optional.
It helps if you put this stuff in the Changes file (ie, new deps added, old deps removed); other practices include providing a POD explaining optional deps, as DBIx::Class does
Learn how Adam Kennedy's RELEASE_TESTING and AUTOMATED_TESTING proposals work, and use them. It is also good if you separate your author tests into xt/ (various toolchains provide a mechanism for this)
- Keep author-only files out of your distribution, including:
- .svn, .git and other Version Control stuff
- In the Debian Perl Group, we use .svn (and sometimes .git) to maintain our packages; if your distributed tarball contains these directories, we cannot update our repository (it aborts so that our own version control stuff doesn't get messed up)
- Add "whatis" entries to your documentation
- They should provide a short description of your modules, and generally begin with a noun
Use the "is a" rule: "Module::Name - thing to do stuff" can be read as "Module::Name is a thing to do stuff"
Put them under the =head1 NAME section
- Do not provide any documentation for private modules, or our tools will get confused (if they're private, use commenting instead of POD, so that no manpages are generated for it)
Consider using Test::Pod to check your PODs for syntax errors
- If you use HTML documentation, please include an index.html (or similar, the name doesn't matter) which refers to the other HTML documentation, provides a table of contents, etc. This allows us to register the documentation with doc-base in Debian so that they are viewable in many documentation viewer tools.
- Make sure all your tests pass (preferably without warnings)
If you must have warnings (ie, checking that your module warns under certain conditions), use Test::Warn to ensure the warnings happen, and to suppress them from diagnostic output
Otherwise, consider using Test::NoWarnings to ensure warnings become FAILs in CPAN Testers reports, so you can investigate further
- Use a standard toolchain; good choices are: