r23905 - in /website/howto: .htaccess adopt.pod

Thu Aug 7 20:16:44 UTC 2008

Author: gregoa
Date: Thu Aug  7 20:16:42 2008
New Revision: 23905

URL: http://svn.debian.org/wsvn/?sc=1&rev=23905
Log:
first version of the 'Debian Perl Group adoption how-to'

Added:
    website/howto/adopt.pod   (with props)
Modified:
    website/howto/.htaccess

Modified: website/howto/.htaccess
URL: http://svn.debian.org/wsvn/website/howto/.htaccess?rev=23905&op=diff
==============================================================================

--- website/howto/.htaccess (original)
+++ website/howto/.htaccess Thu Aug  7 20:16:42 2008
@@ -5,5 +5,6 @@
 IndexIgnore HEADER.html readme.txt *.pod *.tmp
 
 AddDescription "Debian Perl Group uploading how-to" upload.html
+AddDescription "Debian Perl Group adoption how-to" adopt.html
 AddDescription "Quilt for Debian maintainers"  quilt.html
 AddDescription "How to get a CPAN module into Debian" RFP.html

Added: website/howto/adopt.pod
URL: http://svn.debian.org/wsvn/website/howto/adopt.pod?rev=23905&op=file
==============================================================================
--- website/howto/adopt.pod (added)
+++ website/howto/adopt.pod Thu Aug  7 20:16:42 2008
@@ -1,0 +1,284 @@
+=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 no exhaustive tutorial and not necessarily
+complete.
+
+C<Adoption> 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<http://www.debian.org/devel/wnpp/> and
+L<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.
+
+=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. It can be downloaded with
+
+   apt-get source -d $srcpkgname
+
+This source package is then put into the group's subversion repository, as
+described in L<http://pkg-perl.alioth.debian.org/subversion.html>; in short:
+
+   svn-inject -l 2 $srcpkgname_$version.dsc svn+ssh://svn.debian.org/svn/pkg-perl/
+
+You might need to check out the directory again, if you've used svn-inject's
+"-c 0" switch and/or move the tarball around.
+
+Setting the correct svn-bp svn properties (cf.
+F</usr/share/doc/svn-buildpackage/CONFIG>) on C<$newpkg/debian> helps for
+further C<svn-upgrade>'s.
+
+=head2 Helper scripts
+
+F<takeover-for-pkg-perl.sh> (which can be found in our repository at
+C<svn+ssh://svn.debian.org/svn/pkg-perl/scripts/>) automates these two steps
+and 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.
+
+F<fill_svn_props> (again in C<svn+ssh://svn.debian.org/svn/pkg-perl/scripts/>)
+sets the svn-bp svn properties on F<$newpkg/debian>.
+
+=head1 3. Changing the package
+
+After the package is uploaded to the subversion repository it has to be
+adapted to our Policy (L<http://pkg-perl.alioth.debian.org/policy.html>).
+Basically that means going through the files under C<debian/> and taking
+some other "group habits" into account. Short summary:
+
+=head2 debian/changelog
+
+=over
+
+=item *
+
+Close the O/RFA bug or point to the takeover request. (If you have used
+C<takeover-for-pkg-perl.sh> you only need to check the changelog entry.)
+
+=item *
+
+Document all other changes, just 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 <pkg-perl-maintainers at lists.alioth.debian.org>".
+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<debian/compat> or
+adding a F<debian/README.source> file [*]) might be necessary.
+
+=back
+
+=head2 debian/watch
+
+Create or check a F<debian/watch> file, usually using the distribution-based
+CPAN URL.
+
+=head2 debian/copyright
+
+=over
+
+=item *
+
+Add yourself to the copyright for the files under C<debian/>, or create this
+section if necessary.
+
+=item *
+
+Check for formal completeness: upstream source URL (usually the same as in
+F<debian/control>'s Homepage field or in F<debian/watch> can be used),
+copyright (year, person), license, pointers to
+C</usr/share/common-licenses/>, 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 proposed copyright format is recommended; cf.
+L<http://wiki.debian.org/Proposals/CopyrightFormat>.
+
+=back
+
+=head2 debian/rules
+
+=over
+
+=item *
+
+Take a look at the current F<debian/rules> and try to remember anything
+special.
+
+=item *
+
+Often an update is helpful to get the file in line with current practices. A
+simple way is
+
+   $ 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 F<debian/rules> manually is OK too, but often just
+refreshing it with dh-make-perl is faster.
+
+=back
+
+=head3 Helper script
+
+All steps marked with "[*]" can be done semi-automatically with the help of 
+F<packagecheck> which can be found in our repository under
+C<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.
+
+=head1 4. Further tasks
+
+=head2 Docs, examples, ...
+
+=over
+
+=item *
+
+Check which docs are installed (via C<dh_installdocs> or
+F<debian/foo.docs>); 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<debian/>?
+
+=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 makes it quite easy to
+fix these issues in F<debian/control> and/or F<debian/rules>.
+
+=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<debian/control>.
+
+=back
+
+=head2 Patches
+
+Given that the  broad consensus of many members of the Debian Perl Group is
+to use C<quilt> for managing patches against the upstream source:
+
+=over
+
+=item *
+
+If the package already uses C<quilt> make sure the relevant lines are still
+in F<debian/rules> after "d-make-perl --refresh" and maybe refresh the
+patches; cf. L<http://pkg-perl.alioth.debian.org/howto/quilt.html> for
+details.
+
+=item *
+
+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 F<debian/patches/series>
+   refresh the patches
+   try to push/pop them
+   add the C<quilt> fragments to F<debian/rules> and the build dependency
+       into F<debian/control>
+
+=item *
+
+If the package uses C<dpatch> please convert it to C<quilt>.
+
+=back
+
+=head3 Helper script
+
+F<dpatch2quilt> in C<svn+ssh://svn.debian.org/svn/pkg-perl/scripts/> helps to
+convert packages from C<dpatch> to C<quilt>.
+
+=head1 VERSION
+
+$Id$
+
+=head1 AUTHORS
+
+=over
+
+=item * gregor herrmann <gregoa at debian.org>
+
+=back
+
+=head1 COPYRIGHT/LICENSE
+
+Copyright 2008 gregor herrmann <gregoa at debian.org>.  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</usr/share/common-licenses/GPL> and
+the Artistic License in F</usr/share/common-licenses/Artistic>.

Propchange: website/howto/adopt.pod
------------------------------------------------------------------------------
    svn:keywords = Id


