Policy

NAME

policy - Debian Perl Group Policy

INTRODUCTION

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

INDEX

  1. Mandatory mailing lists and such|/”Mandatory mailing lists and such”
  2. debian/changelog handling and versioning|/”debian/changelog handling and versioning”
  3. debian/control handling|/”debian/control handling”
  4. debian/copyright handling|/”debian/copyright handling”
  5. debian/watch handling|/”debian/watch handling”
  6. Package Naming Policy|/”Package Naming Policy”
  7. Test suites|/”Test suites”
  8. Debian Maintainers practice|/”Debian Maintainers practice”
  9. Release Process|/”Release Process”
  10. Authors|/”Authors”
  11. License|/”License”

Mandatory mailing lists and such

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

debian/control handling

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:

Section

Perl packages should be uploaded to the perl section.

Priority

Most Perl packages should be of priority optional.

Maintainer

All group-maintained packages list “Debian Perl Group <pkg-perl-maintainers@lists.alioth.debian.org>”as the maintainer.

Uploaders

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.

Vcs-Git

Some as above for git: An URL pointing to the package’s git repository. That is, for a package called libsomething-perl, https://anonscm.debian.org/git/pkg-perl/packages/libsomething-perl.git.

Vcs-Browser

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://anonscm.debian.org/cgit/pkg-perl/packages/libsomething-perl.git.

Homepage

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.

Testsuite

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.

debian/watch handling

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.

Libraries

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:

  1. Have a source package called libwidget-factory-perl

  2. Produce a single binary package: libwidget-factory-perl

  3. Set up the libwidget-factory-perl binary package so that it also:

    Provides: widgetmaker
    

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.

Applications

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:

  1. Produce a source package called robotmaker
  2. Produce a binary package called robotmaker
  3. 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.

Test suites

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.

Release Process

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 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 PET|https://pet.debian.net/pkg-perl/pet.cgi.

Always feel free to ask others to check a package if in doubt.

VERSION

2016-11-13.1

AUTHORS

* Joachim Breitner

* Daniel Ruoso

* Gustavo Franco

* Gunnar Wolf

* Gregor Herrmann

* Jonathan Yu

LICENSE

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