dpkg-source: add a DEP-3 compliant header to automatic patches

In "3.0 (quilt)" format, dpkg-source can automatically create patches with
the upstream changes applied to the source package. Those patches will now
contain an informative header respecting the DEP-3 proposal where the
Description contains a copy of the last changelog entry, the last uploader
is mentionned in the Author field. Supplementary fields can be added
by a vendor hook "extend-patch-header". The Debian implementation of this
hook automatically adds Bug-Debian and Bug-Ubuntu entries.

Dpkg::Source::Patch has been modified to be able to output a preliminary
header.

debian/changelog

@@ -85,6 +85,8 @@ dpkg (1.15.5) UNRELEASED; urgency=low
     (applies only to source packages using format 1.0). Closes: #482166
     It also recommends usage of 3.0 (quilt) format during dpkg-source -b if it
     detects changes to upstream files that are stored in the .diff.gz.
+  * Add DEP-3 compliant headers to automatic patches created by dpkg-source
+    in 3.0 (quilt) source format. Closes: #543581
 
   [ Updated dpkg translations ]
   * Czech (Miroslav Kure).

scripts/Dpkg/Source/Package/V2.pm

@@ -356,19 +356,20 @@ sub do_build {
         "inclusion)."), $unwanted_binaries) if $unwanted_binaries;
 
     # Create a patch
+    my $autopatch = File::Spec->catfile($dir, "debian", "patches",
+                                        $self->get_autopatch_name());
     my ($difffh, $tmpdiff) = tempfile("$basenamerev.diff.XXXXXX",
                                       DIR => $updir, UNLINK => 0);
     push @Dpkg::Exit::handlers, sub { unlink($tmpdiff) };
     my $diff = Dpkg::Source::Patch->new(filename => $tmpdiff,
                                         compression => "none");
     $diff->create();
+    $diff->set_header($self->get_patch_header($dir, $autopatch));
     $diff->add_diff_directory($tmp, $dir, basedirname => $basedirname,
             %{$self->{'diff_options'}}, handle_binary_func => $handle_binary);
     error(_g("unrepresentable changes to source")) if not $diff->finish();
     # The previous auto-patch must be removed, it has not been used and it
     # will be recreated if it's still needed
-    my $autopatch = File::Spec->catfile($dir, "debian", "patches",
-                                        $self->get_autopatch_name());
     if (-e $autopatch) {
         unlink($autopatch) || syserr(_g("cannot remove %s"), $autopatch);
     }
@@ -421,6 +422,14 @@ sub do_build {
     $self->add_file($debianfile);
 }
 
+sub get_patch_header {
+    my ($self, $dir, $previous) = @_;
+    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
+ check the changelog to (hopefully) learn more on those changes.\n\n";
+}
+
 sub register_autopatch {
     my ($self, $dir) = @_;
     my $autopatch = File::Spec->catfile($dir, "debian", "patches",

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

@@ -26,7 +26,9 @@ use Dpkg::Gettext;
 use Dpkg::ErrorHandling;
 use Dpkg::Source::Patch;
 use Dpkg::IPC;
-use Dpkg::Vendor qw(get_current_vendor);
+use Dpkg::Vendor qw(get_current_vendor run_vendor_hook);
+use Dpkg::Control;
+use Dpkg::Changelog::Parse;
 
 use POSIX;
 use File::Basename;
@@ -295,5 +297,37 @@ sub register_autopatch {
     }
 }
 
+sub get_patch_header {
+    my ($self, $dir, $previous) = @_;
+    my $ch_info = changelog_parse(offset => 0, count => 1,
+        file => File::Spec->catfile($dir, "debian", "changelog"));
+    return '' if not defined $ch_info;
+    my $header = Dpkg::Control->new(type => CTRL_UNKNOWN);
+    $header->{'Description'} = "Upstream changes introduced in version " .
+                               $ch_info->{'Version'} . "\n";
+    $header->{'Description'} .=
+"This patch has been created by dpkg-source during the package build.
+Here's the last changelog entry, hopefully it gives details on why
+those changes were made:\n";
+    $header->{'Description'} .= $ch_info->{'Changes'} . "\n";
+    $header->{'Description'} .=
+"\nThe person named in the Author field signed this changelog entry.\n";
+    $header->{'Author'} = $ch_info->{'Maintainer'};
+    my $text = "$header";
+    run_vendor_hook("extend-patch-header", \$text, $ch_info);
+    $text .= "\n---
+The information above should follow the Patch Tagging Guidelines, please
+checkout http://dep.debian.net/deps/dep3/ to learn about the format. Here
+are templates for supplementary fields that you might want to add:
+
+Origin: <vendor|upstream|other>, <url of original patch>
+Bug: <url in upstream bugtracker>
+Bug-Debian: http://bugs.debian.org/<bugnumber>
+Forwarded: <no|not-needed|url proving that it has been forwarded>
+Reviewed-By: <name and email of someone who approved the patch>
+Last-Update: <YYYY-MM-DD>\n\n";
+    return $text;
+}
+
 # vim:et:sw=4:ts=8
 1;

scripts/Dpkg/Source/Patch.pm

@@ -42,6 +42,7 @@ sub create {
     my ($self, %opts) = @_;
     $self->{'handle'} = $self->open_for_write();
     $self->{'errors'} = 0;
+    $self->{'empty'} = 1;
     if ($opts{'old'} and $opts{'new'}) {
         $opts{'old'} = "/dev/null" unless -e $opts{'old'};
         $opts{'new'} = "/dev/null" unless -e $opts{'new'};
@@ -56,6 +57,11 @@ sub create {
     }
 }
 
+sub set_header {
+    my ($self, $header) = @_;
+    $self->{'header'} = $header;
+}
+
 sub add_diff_file {
     my ($self, $old, $new, %opts) = @_;
     $opts{"include_timestamp"} = 0 unless exists $opts{"include_timestamp"};
@@ -115,6 +121,11 @@ sub add_diff_file {
             chomp;
             error(_g("unknown line from diff -u on %s: `%s'"), $new, $_);
         }
+	if ($self->{'empty'} and defined($self->{'header'})) {
+	    print { $self->{'handle'} } $self->{'header'} or
+		syserr(_g("failed to write"));
+	    $self->{'empty'} = 0;
+	}
         print({ $self->{'handle'} } $_) || syserr(_g("failed to write"));
     }
     close($diffgen) or syserr("close on diff pipe");

scripts/Dpkg/Vendor/Debian.pm

@@ -20,6 +20,7 @@ use warnings;
 
 use base qw(Dpkg::Vendor::Default);
 use Dpkg::Control::Types;
+use Dpkg::Vendor::Ubuntu;
 
 =head1 NAME
 
@@ -45,6 +46,18 @@ sub run_hook {
             [ "insert_after", CTRL_INDEX_SRC, "Uploaders", "Dm-Upload-Allowed" ],
             [ "insert_after", CTRL_PKG_SRC, "Uploaders", "Dm-Upload-Allowed" ],
         );
+    } elsif ($hook eq "extend-patch-header") {
+        my ($textref, $ch_info) = @params;
+	if ($ch_info->{'Closes'}) {
+	    foreach my $bug (split(/\s+/, $ch_info->{'Closes'})) {
+		$$textref .= "Bug-Debian: http://bugs.debian.org/$bug\n";
+	    }
+	}
+
+	my $b = Dpkg::Vendor::Ubuntu::find_launchpad_closes($ch_info->{'Changes'});
+	foreach my $bug (@$b) {
+	    $$textref .= "Bug-Ubuntu: https://bugs.launchpad.net/bugs/$bug\n";
+	}
     } else {
         return $self->SUPER::run_hook($hook, @params);
     }

scripts/Dpkg/Vendor/Default.pm

@@ -109,6 +109,8 @@ sub run_hook {
         return ();
     } elsif ($hook eq "post-process-changelog-entry") {
         my $fields = shift @params;
+    } elsif ($hook eq "extend-patch-header") {
+	my ($textref, $ch_info) = @params;
     }
 
     # Default return value for unknown/unimplemented hooks