scripts: Add support for source package Description and substvars

We support a new source package Description field in debian/control
that will be copied into the .dsc file. The field will also be used
to initialize the new source:Synopsis and source:Extended-Description
substvars that will be available when generating the DEBIAN/control
and .changes files.

Closes: #555743

10 files changed, 79 insertions, 12 deletions

diff --git a/debian/changelog b/debian/changelog
index 984d655e1..8eeff2ef9 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -32,6 +32,11 @@ dpkg (1.19.0) UNRELEASED; urgency=medium
     option. Closes: #873937
   * Make dpkg-genchanges honor substvars in .changes Description field.
     Closes: #856547
+  * Add support for source package Description and substvars. This new
+    field in the debian/control source stanza will be copied into the .dsc
+    file, and will also be used to initialize the new source:Synopsis and
+    source:Extended-Description substvars that will be available when
+    generating the DEBIAN/control and .changes files. Closes: #555743
   * Perl modules:
     - Switch from Dpkg::Util to List::Util, now that the module in the
       new required Perl contains the needed functions.
diff --git a/man/deb-src-control.man b/man/deb-src-control.man
index 2f08ff7e5..259475c2e 100644
--- a/man/deb-src-control.man
+++ b/man/deb-src-control.man
@@ -72,6 +72,17 @@ This documents the most recent version of the distribution policy standards
 this package complies with.
 
 .TP
+.BI Description " \fIshort-description\fP"
+.TQ
+.BI " " "long-description"
+The format for the source package description is a short brief summary on the
+first line (after the \fBDescription\fP field).
+The following lines should be used as a longer, more detailed description.
+Each line of the long description must be preceded by a space, and blank
+lines in the long description must contain a single ‘\fB.\fP’ following
+the preceding space.
+
+.TP
 .BI Homepage: " url"
 The upstream project home page URL.
 
diff --git a/man/deb-substvars.man b/man/deb-substvars.man
index 73513b73a..76110faff 100644
--- a/man/deb-substvars.man
+++ b/man/deb-substvars.man
@@ -112,6 +112,14 @@ The source package version (from the changelog file). This variable is now
 its function, please use the \fBsource:Version\fP or \fBbinary:Version\fP as
 appropriate.
 .TP
+.B source:Synopsis
+The source package synopsis, extracted from the source stanza
+\fBDescription\fP field, if it exists (since dpkg 1.19.0).
+.TP
+.B source:Extended\-Description
+The source package extended description, extracted from the source stanza
+\fBDescription\fP field, if it exists (since dpkg 1.19.0).
+.TP
 .B Installed\-Size
 The approximate total size of the package's installed files. This value is
 copied into the corresponding control file field; setting it will modify
diff --git a/man/dsc.man b/man/dsc.man
index 0992ef5c1..957b164ed 100644
--- a/man/dsc.man
+++ b/man/dsc.man
@@ -106,6 +106,16 @@ Lists all the names and email addresses of co-maintainers of the package,
 in the same format as the \fBMaintainer\fP field.
 Multiple co-maintainers should be separated by a comma.
 .TP
+.BI Description " \fIshort-description\fP"
+.TQ
+.BI " " "long-description"
+The format for the source package description is a short brief summary on the
+first line (after the \fBDescription\fP field).
+The following lines should be used as a longer, more detailed description.
+Each line of the long description must be preceded by a space, and blank
+lines in the long description must contain a single ‘\fB.\fP’ following
+the preceding space.
+.TP
 .BI Homepage: " url"
 The upstream project home page \fIurl\fP.
 .TP
diff --git a/scripts/Dpkg/Control/FieldsCore.pm b/scripts/Dpkg/Control/FieldsCore.pm
index 74c54e686..b100366e1 100644
--- a/scripts/Dpkg/Control/FieldsCore.pm
+++ b/scripts/Dpkg/Control/FieldsCore.pm
@@ -268,7 +268,7 @@ our %FIELDS = (
     },
     'description' => {
         name => 'Description',
-        allowed => ALL_PKG | CTRL_FILE_CHANGES | CTRL_REPO_RELEASE,
+        allowed => ALL_SRC | ALL_PKG | CTRL_FILE_CHANGES | CTRL_REPO_RELEASE,
     },
     'disclaimer' => {
         name => 'Disclaimer',
@@ -618,14 +618,14 @@ our %FIELD_ORDER = (
     ],
     CTRL_PKG_SRC() => [
         qw(format source binary architecture version origin maintainer
-        uploaders homepage standards-version vcs-browser
+        uploaders homepage description standards-version vcs-browser
         vcs-arch vcs-bzr vcs-cvs vcs-darcs vcs-git vcs-hg vcs-mtn
         vcs-svn testsuite testsuite-triggers), @src_dep_fields,
         qw(package-list), @src_checksums_fields, qw(files)
     ],
     CTRL_INDEX_SRC() => [
-        qw(format package binary architecture version priority section
-        origin maintainer uploaders homepage standards-version vcs-browser
+        qw(format package binary architecture version priority section origin
+        maintainer uploaders homepage description standards-version vcs-browser
         vcs-arch vcs-bzr vcs-cvs vcs-darcs vcs-git vcs-hg vcs-mtn vcs-svn
         testsuite testsuite-triggers), @src_dep_fields,
         qw(package-list directory), @src_checksums_fields, qw(files)
diff --git a/scripts/Dpkg/Substvars.pm b/scripts/Dpkg/Substvars.pm
index 920d1613c..1e9f90173 100644
--- a/scripts/Dpkg/Substvars.pm
+++ b/scripts/Dpkg/Substvars.pm
@@ -19,7 +19,7 @@ package Dpkg::Substvars;
 use strict;
 use warnings;
 
-our $VERSION = '1.05';
+our $VERSION = '1.06';
 
 use Dpkg ();
 use Dpkg::Arch qw(get_host_arch);
@@ -268,6 +268,26 @@ sub set_arch_substvars {
     $self->set('Arch', get_host_arch(), $attr);
 }
 
+=item $s->set_desc_substvars()
+
+Defines source description variables: ${source:Synopsis} and
+${source:Extended-Description}.
+
+These will never be warned about when unused.
+
+=cut
+
+sub set_desc_substvars {
+    my ($self, $desc) = @_;
+
+    my ($synopsis, $extended) = split /\n/, $desc, 2;
+
+    my $attr = SUBSTVAR_ATTR_USED | SUBSTVAR_ATTR_AUTO;
+
+    $self->set('source:Synopsis', $synopsis, $attr);
+    $self->set('source:Extended-Description', $extended, $attr);
+}
+
 =item $s->set_field_substvars($ctrl, $prefix)
 
 Defines field variables from a Dpkg::Control object, with each variable
@@ -417,6 +437,10 @@ sub output {
 
 =head1 CHANGES
 
+=head2 Version 1.06 (dpkg 1.19.0)
+
+New method: $s->set_desc_substvars().
+
 =head2 Version 1.05 (dpkg 1.18.11)
 
 Obsolete substvar: Emit an error on Source-Version substvar usage.
diff --git a/scripts/dpkg-genchanges.pl b/scripts/dpkg-genchanges.pl
index 8d56bbdf0..84bdc4ba6 100755
--- a/scripts/dpkg-genchanges.pl
+++ b/scripts/dpkg-genchanges.pl
@@ -233,6 +233,10 @@ foreach (keys %{$src_fields}) {
         set_source_package($v);
     } elsif (m/^Section$|^Priority$/i) {
         $sourcedefault{$_} = $v;
+    } elsif (m/^Description$/i) {
+        # Description in changes is computed, do not copy this field, only
+        # initialize the description substvars.
+        $substvars->set_desc_substvars($v);
     } else {
         field_transfer_single($src_fields, $fields);
     }
diff --git a/scripts/dpkg-gencontrol.pl b/scripts/dpkg-gencontrol.pl
index 98c304a25..2e656a246 100755
--- a/scripts/dpkg-gencontrol.pl
+++ b/scripts/dpkg-gencontrol.pl
@@ -196,6 +196,10 @@ my $src_fields = $control->get_source();
 foreach (keys %{$src_fields}) {
     if (m/^Source$/) {
 	set_source_package($src_fields->{$_});
+    } elsif (m/^Description$/) {
+        # Description in binary packages is not inherited, do not copy this
+        # field, only initialize the description substvars.
+        $substvars->set_desc_substvars($src_fields->{$_});
     } else {
         field_transfer_single($src_fields, $fields);
     }
diff --git a/scripts/dpkg-source.pl b/scripts/dpkg-source.pl
index a4316fbb3..5c356c31a 100755
--- a/scripts/dpkg-source.pl
+++ b/scripts/dpkg-source.pl
@@ -332,7 +332,7 @@ if ($options{opmode} =~ /^(build|print-format|(before|after)-build|commit)$/) {
                         push(@sourcearch, $a) unless $archadded{$a}++;
                     }
                 }
-            } elsif (m/^Homepage$/) {
+            } elsif (m/^(?:Homepage|Description)$/) {
                 # Do not overwrite the same field from the source entry
             } else {
                 field_transfer_single($pkg, $fields);
diff --git a/scripts/t/Dpkg_Control_Fields.t b/scripts/t/Dpkg_Control_Fields.t
index e096c5494..7a6582287 100644
--- a/scripts/t/Dpkg_Control_Fields.t
+++ b/scripts/t/Dpkg_Control_Fields.t
@@ -57,9 +57,9 @@ my %fields = (
         name => 'debian/control source stanza',
         unordered => 1,
         fields => [
-            qw(Bugs Homepage Origin Maintainer Priority Section Source
-               Standards-Version), @test_fields, qw(Uploaders),
-            @vcs_fields, @src_dep_fields
+            qw(Bugs Homepage Description Origin Maintainer Uploaders
+               Priority Section Source Standards-Version),
+            @test_fields, @vcs_fields, @src_dep_fields
         ],
     },
     CTRL_INFO_PKG() => {
@@ -76,8 +76,8 @@ my %fields = (
     CTRL_PKG_SRC() => {
         name => '.dsc',
         fields => [
-            qw(Format Source Binary Architecture Version
-               Origin Maintainer Uploaders Homepage Standards-Version),
+            qw(Format Source Binary Architecture Version Origin Maintainer
+               Uploaders Homepage Description Standards-Version),
             @vcs_fields, @test_fields, @src_dep_fields,
             qw(Package-List),
             @src_files
@@ -98,7 +98,8 @@ my %fields = (
         name => 'Sources',
         fields => [
             qw(Format Package Binary Architecture Version Priority Section
-               Origin Maintainer Uploaders Homepage Standards-Version),
+               Origin Maintainer Uploaders Homepage Description
+               Standards-Version),
             @vcs_fields, @test_fields, @src_dep_fields,
             qw(Package-List Directory),
             @src_files