NAME

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 (http://pkg-perl.alioth.debian.org/git.html).


INDEX

  1. Mandatory mailing lists and such
  2. debian/changelog handling and versioning
  3. debian/control handling
  4. debian/copyright handling
  5. debian/watch handling
  6. Package Naming Policy
  7. Test suites
  8. Debian Maintainers practice
  9. Release Process
  10. Authors
  11. 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 have all our packages installed. They are also encouraged to check our webspace (http://alioth.debian.org/projects/pkg-perl), and our git repositories (http://anonscm.debian.org/git/pkg-perl/). You can watch the work on our git repositories subscribing to our git commits list (http://alioth.debian.org/mail/), 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, git://anonscm.debian.org/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.

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/copyright handling

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 http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/.

The most recent copyright-format specification is referenced in Debian policy under http://www.debian.org/doc/debian-policy/ch-docs.html#s-copyrightformat.


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
 # URL to the package page followed by a regex to search
 https://metacpan.org/release/Foo-Bar   .*/Foo-Bar-v?(\d[\d.-]+)\.(?:tar(?:\.gz|\.bz2)?|tgz|zip)$

(Scanning the distribution-based CPAN URLs is usually much faster than scanning /(by-)module/ ones; author-based URLs become invalid as soon as there's a change in maintainership.)


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:


Debian Maintainers practice

The Debian project has adopted the Debian Maintainers (DM) concept (cf. http://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

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


VERSION

2013-10-10.1


AUTHORS


LICENSE

Copyright (c) 2004-2012 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'.