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://perl-team.pages.debian.net/git.html).
All members of our group should be subscribed to debian-perl@lists.debian.org and read this list (at least skim all messages for Debian Perl Group related stuff). Additionally, every member should be subscribed to pkg-perl-maintainers@lists.alioth.debian.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 git repositories (https://salsa.debian.org/perl-team/modules). You can watch the work on our git repositories via gitlab's watch feature. The commit messages are also sent to #debian-perl at irc.debian.org.
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 unless the first line is * Team upload).
If you change something that has to be noted in debian/changelog, 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 <pkg-perl-maintainers@lists.alioth.debian.org>" 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 <pkg-perl-maintainers@lists.alioth.debian.org>" as the maintainer.
Contains the list of contributors to the specific package, i.e. persons interested in co-maintaining it in the future.
We try to support backporting our packages to oldstable/stable where possible. This affects handling of versioned (build) dependencies.
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.
We try to support bootstrapping efforts, so if build dependencies are exclusively needed for the build tests, they should be annotated with <!nocheck>.
An URL pointing to the package's git repository.
That is,
for a package called libsomething-perl,
https://salsa.debian.org/perl-team/modules/packages/libsomething-perl.git.
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 https://salsa.debian.org/perl-team/modules/packages/libsomething-perl.
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, a Testsuite field with the value autopkgtest-pkg-perl should be added.
Perl packages normally don't need root to build so the Rules-Requires-Root field should be set to no unless it's really needed, in which case it should be set to an appropriate value, see the Debian policy at https://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-rules-requires-root.
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 a modern enough debhelper compatibility level. Typically we would use
Build-Depends: debhelper-compat (= 13)
in debian/control and no debian/compat file.
The pkg-perl group members prefer to directly use debhelper and dh(1) 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=4 https://metacpan.org/release/Foo-Bar .*/Foo-Bar-v?@ANY_VERSION@@ARCHIVE_EXT@$
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:
Provides: widgetmaker
Some consideration is required when other packages may place dependencies on the application component of a package. In this case, we can use a versioned Provides.
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:
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:
Tests designed to be run in automatic builds/installs (usually enabled by setting AUTOMATED_TESTING) are fine.
debian/control:
Build-Depends(-Indep): ..., xvfb, xauth, ...
debian/rules:
override_dh_auto_test: xvfb-run -a dh_auto_test
Some distributions ship embedded modules in inc/, e.g as part of the build system or for testing. While it is OK to have own code in inc/ to extend an existing build system (e.g. Module::Build), an embedded third-party module used for building or testing shouldn't be used but instead packaged in Debian and added as a Build-Depends{,-Indep} entry, while at the same time making sure the embedded version isn't used during package build.
There are some exceptions to this rule, currently:
Build-Depends{,-Indep} accordingly to make sure the embedded version isn't used.libmodule-install-perl doesn't always work, but we expect that for a new package or when upgrading to the lastest upstream version the packager would at least try to use the packaged version.Say a package includes libdevel-checklib-perl in inc/. We should make sure the embedded version isn't used, and set appropriate build-depends:
debian/control:
Build-Depends: ..., libdevel-checklib-perl, ...
debian/rules:
# we want to use the system version of included modules, so # we move the inc away and move it back afterwards override_dh_auto_clean: dh_auto_clean [ ! -d $(CURDIR)/inc.save ] || mv $(CURDIR)/inc.save $(CURDIR)/inc override_dh_auto_configure: [ ! -d $(CURDIR)/inc ] || mv $(CURDIR)/inc $(CURDIR)/inc.save dh_auto_configure
XS Modules (i.e using arch:any) should use hardening build flags.
As a rule, we enable all hardening flags by setting DEB_BUILD_MAINT_OPTIONS to hardening=+all:
debian/rules:
export DEB_BUILD_MAINT_OPTIONS = hardening=+all
However, some hardening flags can cause issues on some architectures, or break the build altogether.
In that case, it is acceptable to enable only a subset of flags for the package:
debian/rules:
export DEB_BUILD_MAINT_OPTIONS = hardening=+bindnow
Please consider re-enabling all the flags vi +all whenever there is a new upstream release in the module or a newer GCC version in Debian.
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, ask at debian-perl@lists.debian.org or in the channel #debian-perl at irc.debian.org in case noone picks up the ready-for-upload package from any of PET (past), DMD (present), or tracker (future).
Always feel free to ask others to check a package if in doubt.
Dual-lived modules (those which are available separately from CPAN as well as in perl itself) can be packaged separately in Debian if and only if the version available on CPAN is greater than that in core, and there is a need for that version in Debian.
When Depending on such packages, declare the package name and version as normal (perl now supports versioned Provides, so separate packages will only be pulled in if needed).
When perl is updated with newer dual-lived modules versions, the separately packaged modules become obsolete. Such packages should not be shipped in a stable release, and should be removed from the archive if there has been no upstream release within two years.
2021-08-21
The canonical source of this document can be found at: https://salsa.debian.org/perl-team/perl-team.pages.debian.net/-/blob/master/policy.pod.
Copyright (c) 2004-2020 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'.