policy - Debian Perl Group Policy
Project Internal Policy
This document describes how we do stuff internally. It is of course work in progress and probably always will be.
We are using git repositories to keep the packages under revision control. Details of working with these repositories are outside the scope of this document; it is recommended that you read the Debian Perl Group Git Guide (https://pkg-perl.alioth.debian.org/git.html).
- Mandatory mailing lists and such|/”Mandatory mailing lists and such”
- debian/changelog handling and versioning|/”debian/changelog handling and versioning”
- debian/control handling|/”debian/control handling”
- debian/copyright handling|/”debian/copyright handling”
- debian/watch handling|/”debian/watch handling”
- Package Naming Policy|/”Package Naming Policy”
- Test suites|/”Test suites”
- Debian Maintainers practice|/”Debian Maintainers practice”
- Release Process|/”Release Process”
Mandatory mailing lists and such¶
All members of our group should be subscribed to email@example.com and read this list (at least skim all messages for Debian Perl Group related stuff). Additionally, every member should be subscribed to firstname.lastname@example.org to receive bug reports and similar information.
All members are encouraged to install and use our packages. They are also encouraged to check our webspace (https://alioth.debian.org/projects/pkg-perl), and our git repositories (https://anonscm.debian.org/cgit/pkg-perl/). You can watch the work on our git repositories subscribing to our git commits list (https://alioth.debian.org/mail/?group_id=30274), listed there as pkg-perl-cvs-commits. The commit messages are also sent to #debian-perl at irc.debian.org.
debian/changelog handling and versioning¶
We use the debian revision to count our releases to the debian archive, not internal steps. So if and only if you do the first change after a release, you add another debian/changelog entry (dch -i). Note that the name and email address in the debian/changelog entry (i.e. after –) should be present in Uploaders: in debian/control (otherwise lintian will think that you are doing an NMU).
If you change something that has to be noted in debian/changelog, just add a line to the current entry (dch -a). The [firstname lastname] markers added by dch are okay to give credit to non-upload-permitted contributors (also for the initial changelog entry).
Important NOTES to other group members may be placed at the top of the current changelog entry of packages that are not yet ready for upload (e.g. why a package is still UNRELEASED etc.).
When pushing a package’s git repository for the first time change the Maintainer field to “Debian Perl Group <email@example.com>” and put your own email address and name in the Uploaders field to show that you feel responsible for the package.
When you make a significant modification to a package in the repository, add your name to the Uploaders field. You should keep the names of other contributors who added their names before you.
The packages maintained by the group should contain the following fields:
Perl packages should be uploaded to the perl section.
Most Perl packages should be of priority optional.
All group-maintained packages list “Debian Perl Group <firstname.lastname@example.org>”as the maintainer.
Contains the list of contributors to the specific package, i.e. persons interested in co-maintaining it in the future.
Build and runtime dependencies
We try to support backporting our packages to oldstable/stable where possible. This affects handling of dual-lifed modules and versioned (build) dependencies.
For dual-lifed modules this means writing (build) dependencies as e.g. “perl (>= 5.10.1) | libtest-simple-perl (>= 0.88)”.
Regarding dependency versions this means adding versions when a package with an older version is still in oldstable or stable. Versions that are already fulfilled by the oldest release in the archive should be left out.
At some point (usually a year after a release) oldstable will be removed from the archive; at that point support for backporting to oldstable becomes moot.
Helpful tools: “rmadison package” for seeing the package releases in all archive areas; “corelist -a Module::Name” to find out when a dual-lifed module was integrated into perl core.
Some as above for git: An URL pointing to the package’s git repository. That is, for a package called libsomething-perl,
An URL pointing to the public Web interface where this package’s base location in the repository can be browsed. For libsomething-perl, it would be
The URL for this module’s upstream homepage. For CPAN modules, unless the author has a specific homepage, you can point to https://metacpan.org/release/Something.
If the package uses the autopkgtest framework|https://pkg-perl.alioth.debian.org/git.html, a Testsuite field with the value autopkgtest-pkg-perl should be added.
The other usual fields should, of course, be present and have sensible values. In particular, try to stick to the highest published Standards-Version and debhelper compatibility level.
The pkg-perl group members prefer to directly use debhelper when packaging. We suggest you don’t use cdbs as part of the build process for packages intended to be group-maintained.
Each package should have the copyright file debian/copyright following the copyright-format 1.0 or newer. copyright-format 1.0 as released together with Debian policy 3.9.3 is documented at https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/.
The most recent copyright-format specification is referenced in Debian policy under https://www.debian.org/doc/debian-policy/ch-docs.html#s-copyrightformat.
Each package should have a watch file (debian/watch) to make manual and automatic checking for new upstream versions easier. The recommended format for a watch file for a typical module libfoo-bar-perl hosted on CPAN is:
version=3 https://metacpan.org/release/Foo-Bar .*/Foo-Bar-v?(\d[\d.-]+)\.(?:tar(?:\.gz|\.bz2)?|tgz|zip)$
Package Naming Policy¶
Where possible, packages should be named in a consistent manner, per the Debian Perl Policy, section 4.2: Module Package Names.
Packages are named differently depending on whether their primary purpose is considered to be a library or an application. The Comprehensive Perl Archive Network (CPAN) is the upstream source of the great majority of our packages. CPAN’s notion of a “distribution” is roughly compatible with Debian’s notion of a “package”, and so, packages are generally named after the distributions they came from.
Suppose there is a hypothetical package called Widget::Factory, which is a library that exposes an interface for other Perl programs. This package also contains a well-known application called widgetmaker. In this case, we should:
Have a source package called libwidget-factory-perl
Produce a single binary package: libwidget-factory-perl
Set up the libwidget-factory-perl binary package so that it also:
Some consideration is required when other packages may place dependencies on the application component of a package, since a virtual package (via Provides) will not allow for version dependencies to be specified. In this case, we can provide a separate binary package for the application.
Occasionally, we encounter Perl distributions that are intended to be used as standalone applications, rather than libraries. These distributions are frequently, but not always, in the App:: namespace. Developers must use their own judgment to decide if this is the case, but if there is any doubt, the issue should be discussed on the mailing list.
Suppose there is a hypothetical distribution called Robot::Maker, which is a suite of software assisting with the design of robot, best known by its users as robotmaker. Since this is an application, we should:
- Produce a source package called robotmaker
- Produce a binary package called robotmaker
- If other libraries depend on the interface provided by library components in this package, but these files are distributed in the same upstream distribution, then we should also produce a binary package called: librobot-maker-perl or similar, which will be a dependency of the robotmaker package.
CPAN distributions typically come with a test suite that is run at build time. As a general rule, we want to run as many tests as possible in order to catch errors. Some details need to be taken into account:
We can’t run tests that need internet access. If they are run by default they must be disabled (if not controlled by a specific environment variable, a patch is required).
We don’t enable tests that are explicitly declared as upstream/author/release tests by the author (typically via an environment variable as RELEASE_TESTING, AUTHOR_TESTING, *or *TEST_AUTHOR).
Test designed to be run in automatic builds/installs (usually enabled by setting AUTOMATED_TESTING) are fine.
Some tests are, even if not declared explicitly as release tests, a bit fragile and tend to break with new releases of the test modules, or test style and not functionality (Test::Perl::Critic, Test::Spelling, Test::Kwalitee, ...). It might be helpful to avoid running them.
Tests that are disabled or not enabled (like the ones needing internet access) should be run manually by the person preparing the package on their local machine before uploading.
Tests that need display access usually work with xvfb:debian/control: Build-Depends(-Indep): ..., xvfb, xauth, ... debian/rules: override_dh_auto_test: xvfb-run -a dh_auto_test
Some tests need versioned build dependencies for dual-lifed modules (e.g. Test::More), cf. Build and runtime dependencies|/”Build and runtime dependencies”.
Debian Maintainers practice¶
The Debian project has adopted the Debian Maintainers (DM) concept (cf. https://www.debian.org/vote/2007/vote_003) in Summer 2007. The pkg-perl group doesn’t see this approach fit for its workflow and its use is discouraged.
If you are a DD, upload but be prepared to receive (at least part of) the blame. If you are not, some DD in the Group will surely sponsor the package. They will check the package first, too, but make sure there is no reason to complain. If you have a package ready for upload, just ask at email@example.com or in the channel #debian-perl at irc.debian.org in case noone picks up the ready-for-upload package from PET|https://pet.debian.net/pkg-perl/pet.cgi.
Always feel free to ask others to check a package if in doubt.
Copyright (c) 2004-2016 by the individual authors and contributors noted above. All rights reserved. This document is free software; you may redistribute it and/or modify it under the same terms as Perl itself
Perl is distributed under your choice of the GNU General Public License or the Artistic License. On Debian GNU/Linux systems, the complete text of the GNU General Public License can be found in `/usr/share/common-licenses/GPL’ and the Artistic License in `/usr/share/common-licenses/Artistic’.