r11747 - in /website: .htaccess howto/ howto/.htaccess howto/upload.pod

Thu Dec 27 01:14:50 UTC 2007

Author: rra
Date: Thu Dec 27 01:14:49 2007
New Revision: 11747

URL: http://svn.debian.org/wsvn/?sc=1&rev=11747
Log:
Add an uploading how-to.  First draft.

Added:
    website/howto/
    website/howto/.htaccess
    website/howto/upload.pod
Modified:
    website/.htaccess

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

--- website/.htaccess (original)
+++ website/.htaccess Thu Dec 27 01:14:49 2007
@@ -12,3 +12,4 @@
 AddDescription "debian/rules template for perl packages" rules-template-noxs
 AddDescription "QA script outputs" qa
 AddDescription "Various documents" docs
+AddDescription "How-to guides" howto

Added: website/howto/.htaccess
URL: http://svn.debian.org/wsvn/website/howto/.htaccess?rev=11747&op=file
==============================================================================
--- website/howto/.htaccess (added)
+++ website/howto/.htaccess Thu Dec 27 01:14:49 2007
@@ -1,0 +1,7 @@
+IndexOptions +SuppressSize +FancyIndexing +DescriptionWidth=*
+
+HeaderName HEADER.html
+ReadmeName readme.txt
+IndexIgnore HEADER.html readme.txt *.pod *.tmp
+
+AddDescription "Debian Perl Group uploading how-to" upload.html

Added: website/howto/upload.pod
URL: http://svn.debian.org/wsvn/website/howto/upload.pod?rev=11747&op=file
==============================================================================
--- website/howto/upload.pod (added)
+++ website/howto/upload.pod Thu Dec 27 01:14:49 2007
@@ -1,0 +1,166 @@
+=head1 NAME
+
+upload - Debian Perl Group uploading how-to
+
+=head1 Introduction
+
+The Debian Perl Group has a lot of active contributors, many of whom are not
+full Debian Developers and hence do not have upload privileges.  One of the
+main ways that Debian Developers can help the group is to upload pending
+updates from Subversion, either after a request on the group mailing list or
+after looking at L<http://pkg-perl.alioth.debian.org/cgi-bin/qareport.cgi> and
+seeing packages in need of uploading.
+
+This step-by-step tutorial lays out one way of processing an upload, suggesting
+verification steps and checks.
+
+=head1 Uploading steps
+
+=head2 Create a working area
+
+Create a working area if you haven't done this before and cd into it.  From
+this point on, I'll assume that all actions take place in that working area.  I
+find it useful to create a directory only for Debian Perl Group work separate
+from the rest of my Debian work.
+
+In that working area, create subdirectories:
+
+   mkdir build-area tarballs old
+
+The first two are used by C<svn-buildpackage>.  The last is used below for
+package comparisons.
+
+=head2 Check out the package
+
+Check out a package from the repository that you're going to upload:
+
+   svn co svn+ssh://svn.debian.org/svn/pkg-perl/trunk/<package>
+
+This will check it out into a directory named after the package inside your
+working area, which is what you want.  Be sure to not add a username before
+svn.debian.org (no user@).  If you do, C<svn-buildpackage --svn-tag> will fail
+later.  Instead, if your local username doesn't match your username on
+svn.debian.org, edit F<~/.ssh/config> and add a stanza like:
+
+   Host svn.debian.org
+       User <user>
+
+where <user> is your username on svn.debian.org.
+
+=head2 Review the changes and update Uploaders
+
+Review debian/changelog to understand what you're uploading.
+
+If you're not already in Uploaders, add yourself.  Also remove any non-DDs from
+Uploaders except those Debian Maintainers who are authorized to upload this
+package in case any were left over from previous group packaging practices.
+
+Update the signature and timestamp for the package with:
+
+    dch -r
+
+(and then exit the editor if you don't need to change anything else).  This
+will also change the signature of the most recent changelog entry to you.
+
+Commit those changes with C<svn commit>.
+
+=head2 Download the upstream tarball
+
+Download the upstream tarball.  If this is just a Debian revision of a package
+already in the archive, do that with:
+
+    cd tarballs
+    apt-get -t unstable source -d --tar-only <package>
+
+Otherwise, cd to the package directory and run:
+
+    uscan --force-download --rename --destdir ../tarballs
+
+and double-check that the upstream URL from which C<uscan> downloaded the
+tarball looks reasonable.
+
+=head2 Build the package
+
+Build the package with:
+
+    svn-buildpackage
+
+(I assume that your F<~/.svn-buildpackage.conf> file is already set up with the
+options you want to use, set up to build in an unstable chroot if needed, and
+so forth.)
+
+=head2 Do a basic sanity check on the package
+
+Go to the F<build-area> directory and do a basic sanity check on the package:
+
+       lintian -iI *.changes
+       lsdiff -z *.diff.gz
+       debc *.changes
+
+C<lsdiff> (from the patchutils package) will tell you if there are any changes
+outside of the debian directory; if so, they may be accidental or the package
+maybe should use quilt, but in any case they're worthy of special review.
+C<debc> shows you the metadata (C<dpkg -I>) and contents (C<dpkg -c>) for each
+built package.
+
+=head2 Compare against previous version
+
+If the package already exists in the archive, see what changed.  Go to the
+F<old> directory created above, and then download the current package:
+
+    apt-get -t unstable source -d <package>
+
+(Obviously, do this on a system with unstable in the apt F<sources.list>.)
+Then cd up one directory, to the top of your working directory, and compare the
+new and old package with debdiff:
+
+    debdiff old/*.dsc build-area/*.dsc | less
+
+For the wildcards to work, you'll need to delete the contents of your
+build-area and old directories after you finish with each package.  Make sure
+the changes look reasonable.
+
+=head2 Upload the package
+
+C<debsign> the *.changes file in build-area and the C<dput> or C<dupload> it to
+the archive.
+
+=head2 Tag the package
+
+Change directories back to the checkout of the package and tag it:
+
+    svn-buildpackage --svn-tag --svn-tag-only
+
+Be sure that you've configured C<svn-buildpackage> not to modify
+F<debian/changelog> after a tag, or if you haven't, add the C<--svn-noautodch>
+flag.
+
+=head1 Version
+
+$Id$
+
+=head1 Authors
+
+=over
+
+=item * Russ Allbery <rra at debian.org>
+
+=back
+
+=head1 License
+
+Copyright 2007 Russ Allbery <rra 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>.
+
+=for comment
+Local variables:
+auto-fill-mode: t
+fill-column: 79
+End:
+vim:tw=79


