r71623 - in /website/howto: .htaccess repacking.pod

[gregoa at users.alioth.debian.org]

Author: gregoa
Date: Fri Mar 18 20:13:22 2011
New Revision: 71623

URL: http://svn.debian.org/wsvn/?sc=1&rev=71623
Log:
first commit of repacking.pod

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

Modified: website/howto/.htaccess
URL: http://svn.debian.org/wsvn/website/howto/.htaccess?rev=71623&op=diff
==============================================================================
--- website/howto/.htaccess (original)
+++ website/howto/.htaccess Fri Mar 18 20:13:22 2011
@@ -10,3 +10,4 @@
 AddDescription "Quilt for Debian maintainers (copy-pastable version)"  quilt-copyable.html
 AddDescription "How to get a CPAN module into Debian" RFP.html
 AddDescription "Add missing upstream tarballs to the repository" missingupstream.html
+AddDescription "How to repackage upstream tarballs" repacking.html

Added: website/howto/repacking.pod
URL: http://svn.debian.org/wsvn/website/howto/repacking.pod?rev=71623&op=file
==============================================================================
--- website/howto/repacking.pod (added)
+++ website/howto/repacking.pod Fri Mar 18 20:13:22 2011
@@ -1,0 +1,95 @@
+=head1 NAME
+
+repacking - How to repackage upstream tarballs
+
+=head1 0. Introduction
+
+Sometimes it is necessary to repack an upstream tarball. This should happen
+rarely and only with good reasons -- usually in order to remove non-free
+material.
+
+This how-to provides an overview about an easy way to do it.
+
+=head1 1. Version
+
+First of all, decide about the version suffix.
+
+Repacked tarballs are denoted by adding a suffix to the upstream version
+number, the most prominent example being C<+dfsg> (referring to the DFSG,
+and used when non-free stuff is removed); another possibility is C<+ds> for
+"Debian Source", sometimes used when e.g. included third-party libraries are
+removed.
+
+When you have chosen your version suffix, add it to the topmost entry in
+F<debian/changelog>.
+
+=head1 2. Repacking scripts
+
+=head2 repack.stub
+
+Copy F<repack.stub> (from the scripts/ directory in our subversion
+repository) to the debian/ directory of the source package.
+
+It is a short shell script that calls F<repack.sh> (also available in the
+scripts/ directory in our subversion repository). -- Note that F<repack.sh>
+must be either in C<$PATH> or in F<../../scripts/repack.sh> later.
+
+=head2 repack.local
+
+Create F<debian/repack.local>. It is a shell fragment that gets sourced by
+F<repack.sh>.
+
+You can set some variables there and use a few functions. For details see
+B<perldoc repack.stub>.
+
+(Note that you can do other things in F<debian/repack.local> since this
+sourced by a shell script; just be careful :))
+
+A typical F<debian/repack.local> might look like:
+
+    MANIFEST=1
+    rm docs/rfc*
+
+=head1 3. Watch file
+
+Since we add a version suffix we need a dversionmangle in F<debian/watch>,
+and we also want to call F<debian/repack.stub> automatically.
+
+Change your watch file to something like:
+
+    opts=dversionmangle=s/\+dfsg$// \
+        http://search.cpan.org/dist/The-Module/    .*/The-Module-v?(\d[\d.-]+)\.(?:tar(?:\.gz|\.bz2)?|tgz|zip)$ \
+        debian sh debian/repack.stub
+
+=head1 4. Copyright file
+
+The reason for repacking should be noted in F<debian/copyright> (Debian
+Policy 12.5). According to L<http://dep.debian.net/deps/dep5/>, this should
+be noted in the "Header paragraph" in the (Source or) Comment field.
+
+=head1 5. Package upgrades
+
+From now on, B<uscan> or B<svn-upgrade --uscan> should "just work".
+
+=head1 VERSION
+
+$Id$
+
+=head1 AUTHORS
+
+=over
+
+=item * gregor herrmann <gregoa at debian.org>
+
+=back
+
+=head1 COPYRIGHT/LICENSE
+
+Copyright (c) 2011 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 systems, the complete text of version 1 of the GNU
+General Public License can be found in F</usr/share/common-licenses/GPL-1> and
+the Artistic License in F</usr/share/common-licenses/Artistic>.