dpkg-source: support debian/source/patch-header

The content of this file is used as header of the automatic patch
generated in formats "2.0" and "3.0 (quilt)".

debian/changelog

@@ -11,6 +11,8 @@ dpkg (1.15.5.4) UNRELEASED; urgency=low
     format "3.0 (quilt)" so that it behaves more like 1.0 and its single diff
     that is constantly updated with all upstream changes. Useful if the
     workflow is VCS based and can't generate a full patch set.
+  * dpkg-source now uses debian/source/patch-header as header of the automatic
+    Debian patch in format "3.0 (quilt)".
 
  -- Raphael Hertzog <hertzog@debian.org>  Sun, 29 Nov 2009 18:15:16 +0100
 

man/dpkg-source.1

@@ -461,9 +461,12 @@ apparently unapplied.
 Use \fBdebian/patches/debian-changes\fP instead of
 \fBdebian/patches/debian-changes-\fP\fIversion\fP for the name of the
 automatic patch generated during build. This option is particularly
-useful when you maintain a package in a VCS and you can't reliably
-generate a patch set, instead you just want to store the current
-diff with upstream in a single patch.
+useful when the package is maintained in a VCS and a patch set can't reliably
+be generated. Instead the current diff with upstream should be stored in a
+single patch. When using this option, it is recommended to create
+a debian/source/patch-header file explaining how the Debian changes can be
+best reviewed, for example in the VCS that is used.
+
 .PP
 .B Extract options
 .TP
@@ -535,6 +538,9 @@ Here's an example of such a file:
 .P
 Note: \fBformat\fR options are not accepted in this file, you should
 use \fBdebian/source/format\fR instead.
+.SS debian/source/patch-header
+Free form text that is put on top of the automatic patch generated
+in formats "2.0" or "3.0 (quilt)".
 .SS debian/patches/series
 This file lists all patches that have to be applied (in the given order)
 on top of the upstream source package. Leading and trailing spaces are

scripts/Dpkg/Source/Package/V2.pm

@@ -431,6 +431,14 @@ sub do_build {
 
 sub get_patch_header {
     my ($self, $dir, $previous) = @_;
+    my $ph = File::Spec->catfile($dir, "debian", "source", "patch-header");
+    my $text;
+    if (-f $ph) {
+        open(PH, "<", $ph) || syserr(_g("cannot read %s"), $ph);
+        $text = join("", <PH>);
+        close(PH);
+        return $text;
+    }
     return "Description: Undocumented upstream changes
  This patch has been created by dpkg-source during the package build
  but it might have accumulated changes from several uploads. Please

scripts/Dpkg/Source/Package/V3/quilt.pm

@@ -294,6 +294,14 @@ sub register_autopatch {
 
 sub get_patch_header {
     my ($self, $dir, $previous) = @_;
+    my $ph = File::Spec->catfile($dir, "debian", "source", "patch-header");
+    my $text;
+    if (-f $ph) {
+        open(PH, "<", $ph) || syserr(_g("cannot read %s"), $ph);
+        $text = join("", <PH>);
+        close(PH);
+        return $text;
+    }
     my $ch_info = changelog_parse(offset => 0, count => 1,
         file => File::Spec->catfile($dir, "debian", "changelog"));
     return '' if not defined $ch_info;
@@ -310,7 +318,7 @@ those changes were made:\n";
     $header->{'Description'} .=
 "\nThe person named in the Author field signed this changelog entry.\n";
     $header->{'Author'} = $ch_info->{'Maintainer'};
-    my $text = "$header";
+    $text = "$header";
     run_vendor_hook("extend-patch-header", \$text, $ch_info);
     $text .= "\n---
 The information above should follow the Patch Tagging Guidelines, please