Document VCS fields

Uses 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
 - list some Vcs-<foo> fields by name in the lists in §5.2 and §5.4
 - declared repositories track development of the Debian source
   package, not just the upstream code
 - Vcs-Browser can be a web interface using any protocol (e.g., HTTPS
   is fine)
 - picking a good branch is optional
 Thanks to Russ Allbery for several improvements to the text.]

diff --git a/policy.sgml b/policy.sgml
index aa42b5d078c84b822aa89a1b04eeb7b931713432..6e7c69ec5672f3bf893841cc6904aa93c18df8cd 100644 (file)
--- 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-Browser</tt>, <tt>Vcs-Git</tt>, et al.</qref></item>
          </list>
        </p>
 
@@ -2725,6 +2726,7 @@ Package: libc6
          <item><qref id="f-Uploaders"><tt>Uploaders</tt></qref></item>
          <item><qref id="f-DM-Upload-Allowed"><tt>DM-Upload-Allowed</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.</qref></item>
          <item><qref id="f-Standards-Version"><tt>Standards-Version</tt></qref> (recommended)</item>
          <item><qref id="sourcebinarydeps"><tt>Build-Depends</tt> et al</qref></item>
          <item><qref id="f-Checksums"><tt>Checksums-Sha1</tt>
@@ -3739,6 +3741,53 @@ 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 Debian source package is developed.
+
+           <taglist>
+             <tag><tt>Vcs-Browser</tt></tag>
+             <item>
+               <p>
+                 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 used for packaging. Ideally, it also locates the
+                 branch used for development of new versions of the Debian
+                 package.
+               </p>
+               <p>
+                 In the case of Git, the value consists of a URL, optionally
+                 followed by the word <tt>-b</tt> and the name of a branch in
+                 the indicated repository, following the syntax of 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>