Bug#720507: .dsc field for dgit

[Ian Jackson <ijackson@chiark.greenend.org.uk>]

Package: debian-policy
Version: 3.9.4.0

I have been working on a new tool for integration between the Debian
archive and git.  The best available description is probably its
manpage:
  http://www.chiark.greenend.org.uk/~ijackson/2013/dgit.html

dgit uses a new field in .dsc files, which I have called
Vcs-Dgit-Master.  Here is my proposed policy amendment to describe it.

There is no need for anything other than dgit to know about this
field or its implications, although QA tools could profitably check
some of the facts stated in the spec.

Thanks,
Ian.


diff --git a/policy.sgml b/policy.sgml
index 5760a3f..f8051c0 100644
--- a/policy.sgml
+++ b/policy.sgml
@@ -2655,7 +2655,7 @@ Package: libc6
 	    <item><qref id="sourcebinarydeps"><tt>Build-Depends</tt> et al</qref></item>
 	    <item><qref id="f-Standards-Version"><tt>Standards-Version</tt></qref> (recommended)</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.</qref></item>
+	    <item><qref id="f-VCS-fields"><tt>Vcs-Browser</tt>, <tt>Vcs-Git</tt>, et al. (except <tt>Vcs-Dgit-Master</tt>)</qref></item>
 	  </list>
 	</p>
 
@@ -3809,6 +3809,44 @@ Checksums-Sha256:
 		  package.
 		</p>
 	      </item>
+
+	      <tag>
+		<tt>Vcs-Dgit-Master</tt>
+	      </tag>
+	      <item>
+		<p>
+	          Present only in <file>.dsc</file>
+                  (and <file>Sources</file>).  Must not be present
+                  in <file>debian/control</file>.  Generated
+                  automatically as appropriate.
+		</p>
+		<p>
+		  Declares that this source package corresponds exactly
+		  to the referenced git commit.
+		</p>
+		<p>
+		  The format is a single git commit hash, presented in
+		  full, followed optionally by whitespace and other
+		  data to be defined in future extensions.  This is a
+		  folded field.
+		</p>
+		<p>
+	          The commit hash must refer to a git commit which is
+	          available in dgit-repos.  Specifically, the commit
+	          must be available in the well-known dgit-repos
+	          location for the package named in <tt>Source</tt>,
+                  which is currently
+ <tt>git://dgit.debian.net/dgit-repos/</tt><var>package</var><tt>.git</tt>.
+                  The commit must be reachable in that tree from at
+                  least one git ref whose name
+                  matches <tt>refs/dgit/*</tt> (but not necessarily
+                  the ref <tt>refs/dgit/</tt><var>suite</var> for the
+                  suite in which the <file>.dsc</file> is found).
+		</p>
+		<p>
+		  This field is used by <prgn>dgit</prgn>.
+		</p>
+	      </item>
 	    </taglist>
 	  </p>
 	</sect1>