Bug#654958: debian-policy: Document VCS fields.

[Jonathan Nieder <jrnieder@gmail.com>]

Charles Plessy wrote:

> Would the following patch be acceptable now ?

My feedback got no replies, so I can only assume that everyone was so
awestruck by the suggestions that they were lost for words.

Here's an updated patch.  Improvements welcome.

Looking forward to your thoughts,
Jonathan

From: Charles Plessy <plessy@debian.org>
Date: Sat, 7 Jan 2012 15:00:30 +0900
Subject: Document VCS fields, using Developers's Reference §6.2.5 for inspiration.

Closes: #654958

[jrnieder@gmail.com:
 - declared repositories should be publicly accessible
 - Vcs-Browser should point to a webapp
 - Vcs-<system> should use the version control system's conventional syntax
 - if multiple branches are used for packaging (e.g., "stable",
   "testing", "sid"), any one of them will do
 - for Vcs-Git, "-b <branch>" can be omitted when the intended branch is the
   default branch ]
---
 policy.sgml |   48 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 48 insertions(+)

diff --git a/policy.sgml b/policy.sgml
index 52dbb26a..371123e1 100644
--- a/policy.sgml
+++ b/policy.sgml
@@ -2631,6 +2631,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 fields</tt></qref></item>
 	  </list>
 	</p>
 
@@ -2728,6 +2729,7 @@ Package: libc6
 	  <item><qref id="f-Checksums"><tt>Checksums-Sha1</tt>
 	      and <tt>Checksums-Sha256</tt></qref> (recommended)</item>
 	  <item><qref id="f-Files"><tt>Files</tt></qref> (mandatory)</item>
+	  <item><qref id="f-VCS-fields"><tt>VCS fields</tt></qref></item>
 	</list>
 	</p>
 
@@ -3737,6 +3739,52 @@ Checksums-Sha256:
 	    details.
 	  </p>
 	</sect1>
+
+	<sect1 id="f-VCS-fields">
+	  <heading>Version Control System (VCS) fields</heading>
+
+	  <p>
+	    Debian source packages are increasingly developed using VCSs.  The
+	    purpose of the following fields is to indicate a publicly accessible
+	    repository where the package is developed.
+
+	    <taglist>
+	      <tag><tt>Vcs-Browser</tt></tag>
+	      <item>
+		<p>
+		  HTTP URL of a web interface for browsing the repository.
+		</p>
+	      </item>
+
+	      <tag>
+		<tt>Vcs-Arch</tt>, <tt>Vcs-Bzr</tt> (Bazaar), <tt>Vcs-Cvs</tt>,
+		<tt>Vcs-Darcs</tt>, <tt>Vcs-Git</tt>, <tt>Vcs-Hg</tt>
+		(Mercurial), <tt>Vcs-Mtn</tt> (Monotone), <tt>Vcs-Svn</tt>
+		(Subversion)
+	      </tag>
+	      <item>
+		<p>
+		  The field name identifies the VCS. The field's value uses the
+		  version control system's conventional syntax for describing
+		  repository locations and should be sufficient to locate the
+		  repository and access it anonymously on a branch used for
+		  packaging.
+		</p>
+		<p>
+		  In the case of Git, the value consists of a Git URL
+		  optionally followed by the word <tt>-b</tt> and the name of
+		  a branch in the indicated repository, like with the
+		  <tt>git clone</tt> command.  If no branch is specified, the
+		  packaging should be on the default branch.
+		</p>
+		<p>
+		  More than one different VCS may be specified for the same
+		  package.
+		</p>
+	      </item>
+	    </taglist>
+	  </p>
+	</sect1>
       </sect>
 
       <sect>
-- 
1.7.10.4