adopt - How to adopt packages for the Debian Perl Group
This short How-to tries to give some useful hints for adopting packages for the Debian Perl Group. It's not an exhaustive tutorial and not necessarily complete.
Adopting means to take over a package for the Debian Perl Group that was
maintained by someone else beforehand; the package may be officially
orphaned or offered for adoption, or the previous maintainer may just have
asked for or agreed to having it moved to the group.
If the package was orphaned or offered for adoption, the usual manipulations of the respective bugs are required (changing owner and title, closing the bug in the changelog); cf. http://www.debian.org/devel/wnpp/ and http://www.debian.org/doc/developers-reference/pkgs.html#adopting.
In case of an informal adoption request it is recommended to provide some evidence of the original maintainer's request in the changelog, e.g. a bug number, a link to a mailing list post, etc.
Usually the latest version of the package in the archive will be the starting point for the adoption.
takeover-for-pkg-perl.sh (which can be found in our repository at
svn+ssh://svn.debian.org/svn/pkg-perl/scripts/) automates the
injection of the package into svn, adding appropriate svn-buildpackage
properties to the debian directory. It also adds a line to the
changelog, with either a bug number for an RFA or a link to a message
with the request for takeover from the maintainer.
To do this manually instead, use apt-get source to fetch the latest
version in the archive, and then follow the steps for an initial
upload described at
http://pkg-perl.alioth.debian.org/subversion.html#3__initial_upload.
Use fill_svn_props (again in
svn+ssh://svn.debian.org/svn/pkg-perl/scripts/) to set the svn-bp
svn properties if you forget the '--setprops' option to svn-inject.
After the package is uploaded to the subversion repository it has to be
adapted to our Policy (http://pkg-perl.alioth.debian.org/policy.html).
Basically that means going through the files under debian/ and taking
some other "group habits" into account. Short summary:
Close the O/RFA bug or point to the takeover request. (If you have used
takeover-for-pkg-perl.sh you only need to check the changelog entry.)
Document all other changes, just as usual.
Typical actions, besides checking the short/long descriptions and the other fields:
Change maintainer to "Debian Perl Group <pkg-perl-maintainers@lists.alioth.debian.org>". Add yourself to Uploaders, remove old maintainer or move him/her to Uploaders, depending on the kind of request/takeover. [*]
Add/change the Homepage and Vcs-* fields appropriately. [*]
Check Standards-Version and debhelper versioned dependency and adjust appropriately. Of course further changes (adapting debian/compat or adding a debian/README.source file [*]) might be necessary.
Create a new or check an existing debian/watch file. Whenever possible, please use a dist-based URL, such as
http://search.cpan.org/dist/Foo-Bar/ .*/Foo-Bar-v?(\d[\d.-]+)\.(?:tar(?:\.gz|\.bz2)?|tgz|zip)$
instead of pointing to the module or author directories in CPAN, or in external repositories. [*]
Add yourself to the copyright for the files under debian/, or create this
section if necessary.
Check for formal completeness: upstream source URL (usually the same as in
debian/control's Homepage field or in debian/watch can be used),
copyright (year, person), license, pointers to
/usr/share/common-licenses/, etc.
Check if all copyright holders and all licenses are actually included. Tools like
licensecheck --recursive --copyright .
or a simple
grep -ir copyright *
can help.
Switching to the new proposed copyright format is recommended; cf. http://wiki.debian.org/Proposals/CopyrightFormat.
Carefully review the existing debian/rules. In order to maintain consistency and ease maintenance, you will probably prefer replacing it with our standard templates.
A simple way for bringing the file in line with current practices is:
Take a look at the current debian/rules and try to remember anything special.
$ dh-make-perl --refresh --dh (5|7)
$ svn diff
$ $EDITOR debian/rules
make changes if necessary
re-add "special" lines (You remembered them, right? If not "svn diff"
has told you anyway.)
Of course changing debian/rules manually is OK too, but often just refreshing it with dh-make-perl is faster.
All steps marked with "[*]" can be done semi-automatically with the help of
packagecheck which can be found in our repository under
svn+ssh://svn.debian.org/svn/pkg-perl/scripts/qa/.
packagecheck -A -C -c
is often a good first step after svn-injecting the package.
Check which docs are installed (via dh_installdocs or
debian/foo.docs); often there's a useless README included. And some
interesting file might be missing.
Same for examples: too many or any missing?
Any other superfluous/missing files under debian/?
Any missing/obsolete lintian overrides?
Sometimes tests are not run because of either missing build dependencies or missing environment variables. The build log usually makes it quite easy to fix these issues in debian/control and/or debian/rules.
A look at Makefile.PL and META.yml for the required other modules sometimes leads to necessary adjustments of the (build) dependencies in debian/control.
Given that the broad consensus of many members of the Debian Perl Group is
to use quilt for managing patches against the upstream source:
If the package already uses quilt make sure the relevant lines are still
in debian/rules after "dh-make-perl --refresh" and maybe refresh the
patches; cf. http://pkg-perl.alioth.debian.org/howto/quilt.html for
details.
If the upstream source is patched directly (look at the .diff.gz after building the package) please convert these patches to quilt:
$ mkdir debian/patches && diff2patches $DIFFGZ
reverse apply the patches
create debian/patches/series
refresh the patches
try to push/pop them
add the quilt fragments to F<debian/rules> and the build dependency
into debian/control
If the package uses dpatch please convert it to quilt.
dpatch2quilt in svn+ssh://svn.debian.org/svn/pkg-perl/scripts/ helps to
convert packages from dpatch to quilt.
$Id: adopt.pod 47165 2009-11-14 17:54:56Z jawnsy-guest $
Copyright (c) 2008 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.