=head1 NAME adopt - How to adopt packages for the Debian Perl Group =head1 0. Introduction 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. C 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. =head1 1. Formal steps 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. L and L. 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. =head1 2. Getting the package (into the repository) Usually the latest version of the package in the archive will be the starting point for the adoption. C (which can be found in the B package) automates the injection of the package into Git. 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. If the package was maintained in a gbp-style Git repository, use the C<-g URL> option. Otherwise C will use L to import the packaging history from snapshots.debian.org. You may consider using C<-n> option too, so you have the chance to review and improve the commits before pushing them. To do this manually instead, use C to fetch the latest version in the archive, and then follow the steps described at L. =head1 3. Changing the package After the package has been pushed it has to be adapted to our Policy (L). Basically that means going through the files under C and taking some other "group habits" into account. A short summary follows. =head2 Helper script All following steps marked with "[*]" can be done semi-automatically with the help of C which can be found in the B package. dpt packagecheck -A -C -c is often a good first step after importing the package into Git. =head2 debian/changelog =over =item * Close the O/RFA bug or point to the takeover request. (If you have used C you only need to check the changelog entry.) =item * Document all other changes, as usual. =back =head2 debian/control Typical actions, besides checking the short/long descriptions and the other fields: =over =item Maintainer/Uploaders Change maintainer to "Debian Perl Group ". Add yourself to Uploaders, remove old maintainer or move him/her to Uploaders, depending on the kind of request/takeover. [*] =item Homepage, Vcs* Add/change the Homepage and Vcs-* fields appropriately. [*] =item debhelper/Policy Check Standards-Version and debhelper versioned dependency and adjust appropriately. Of course further changes (adapting F or adding a F file [*]) might be necessary. =back =head2 debian/watch Create a new or check an existing F file. Whenever possible, please use a dist-based URL, such as https://metacpan.org/release/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. [*] =head2 debian/copyright =over =item * Add yourself to the copyright for the files under C, or create this section if necessary. =item * Check for formal completeness: upstream source URL (usually the same as in F's Homepage field or in F can be used), copyright (year, person), license, pointers to C, etc. =item * Check if all copyright holders and all licenses are actually included. Tools like licensecheck --recursive --copyright . or a simple grep -ir copyright * can help. =item * Switching to the new copyright format is recommended; cf. L. C is useful to detect and fix common errors. =back =head2 debian/rules =over =item * Carefully review the existing F. In order to maintain consistency and ease maintenance, you will probably prefer replacing it with our standard templates (i.e. the three-lines tiny dh version). =item * A simple way for bringing the file in line with current practices is: Take a look at the current F and try to remember anything special. $ dh-make-perl refresh $ git diff $ $EDITOR debian/rules make changes if necessary re-add "special" lines (You remembered them, right? If not "git diff" has told you anyway.) Of course changing F manually is OK too, but refreshing it with L is often faster. =back =head1 4. Further tasks =head2 Docs, examples, ... =over =item * Check which docs are installed (via C or F); often there's a useless README included. And some interesting file might be missing. =item * Same for examples: too many or any missing? =item * Any other superfluous/missing files under C? =item * Any missing/obsolete Lintian overrides? =back =head2 Dependencies, tests =over =item * Sometimes tests are not run because of either missing build dependencies or missing environment variables. The build log usually helps fixing these issues in F and/or F. =item * A look at Makefile.PL and META.yml for the required other modules sometimes leads to necessary adjustments of the (build) dependencies in F. =back =head2 Patches The broad consensus of many members of the Debian Perl Group is to use C for managing patches against the upstream source, and source format C<3.0 (quilt)> for the packaging. Make sure the patches apply cleanly and have headers according to DEP3: L =head1 VERSION 2018-05-17.1 =head1 AUTHORS =over =item * gregor herrmann =back =head1 COPYRIGHT/LICENSE Copyright (c) 2008-2018 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 F and the Artistic License in F.