Bug#720507: .dsc field for dgit [and 1 more messages]

[Charles Plessy <plessy@debian.org>]

Thanks Ian and everybody for your comments.

Here is a simplified patch, written under the assumption of "Dgit" for the
name.

I made the following changes:

 - Removed mention that this field is only in Debian source control files and
   must not be present in source package control files: it is obvious from the
   sections 5.2 and 5.4, and this is not done for other fields.

 - Reorganised in two paragrpahs, one for the syntax, and one for the purpose
   and implementation.

 - I removed the location of dgit-repos, and the warning that searching in
   <tt>refs/dgit/</tt><var>suite</var> is too strict.  To compensate, I
   added an invitation to read the manual.

Altogether, I hope that my proposition strikes a good balance.  The chapter 5
is the specification of the control fields, and I think that a more precide
description on Dgit's implementation would be off-topic there.

Here is the patch, what do you think of it ?

@@ -2759,6 +2759,7 @@ Package: libc6
          <item><qref id="f-Uploaders"><tt>Uploaders</tt></qref></item>
          <item><qref id="f-Homepage"><tt>Homepage</tt></qref></item>
          <item><qref id="f-VCS-fields"><tt>Vcs-Browser</tt>, <tt>Vcs-Git</tt>, et al.</qre
+         <item><qref id="f-Dgit"><tt>Dgit</tt></qref></item>
          <item><qref id="f-Standards-Version"><tt>Standards-Version</tt></qref> (recommend
          <item><qref id="sourcebinarydeps"><tt>Build-Depends</tt> et al</qref></item>
          <item><qref id="f-Package-List"><tt>Package-List</tt></qref> (recommended)</item>
@@ -3840,6 +3841,26 @@ Checksums-Sha256:
            this value is assumed for paragraphs lacking this field.
          </p>
        </sect1>
+
+       <sect1 id="f-Dgit">
+         <heading><tt>Dgit</tt></heading>
+
+         <p>
+           Folded field containing a single git commit hash, presented in
+           full, followed optionally by whitespace and other data to be
+           defined in future extensions.
+         </p>
+
+         <p>
+           Declares that the source package corresponds exactly to a
+           referenced commit in a Git repository available at the canonical
+           location called <em>dgit-repos</em>, used by <prgn>dgit</prgn>, a
+           bidirectional gateway between the Debian archive and Git.  The
+           commit is reachable from at least one reference whose name matches
+           <tt>refs/dgit/*</tt>.  See the manual page of <prgn>dgit</prgn> for
+           further details.
+         </p>
+       </sect1>
       </sect>
 
       <sect>

Have a nice week-end,

-- 
Charles Plessy
Tsurumi, Kanagawa, Japan