Add XS-Vcs-*; #391023

git-svn-id: svn://anonscm.debian.org/ddp/manuals/trunk/developers-reference@4655 313b444b-1b9f-4f58-a734-7bb04f332e8d

diff --git a/debian/changelog b/debian/changelog
index f23e0d01958323b304ee82f917dc9e8ae80bd732..38913601f75b456d6e5d429402d3e18f1fc0ecbe 100644 (file)
--- a/debian/changelog
+++ b/debian/changelog
@@ -15,6 +15,7 @@ developers-reference (3.3.9) unstable; urgency=low
   * Fix typo. Closes: #405453
   * More details on how to write documentation. Thanks, Josh Triplett.
     Closes: #422750
+  * Add XS-Vcs-*. Thanks to Stefano Zacchiroli. Closes: #391023
 
  -- Andreas Barth <aba@not.so.argh.org>  Sat, 16 Jun 2007 11:41:41 -0600
 

diff --git a/developers-reference.sgml b/developers-reference.sgml
index ee8366f94e4ea104353d703a3bae9521ef0acef3..fd11da662724442e9ddb410b7c477c8ef23eca21 100644 (file)
--- a/developers-reference.sgml
+++ b/developers-reference.sgml
@@ -7,7 +7,7 @@
   <!ENTITY % dynamicdata  SYSTEM "dynamic.ent" > %dynamicdata;
 
   <!-- CVS revision of this document -->
-  <!ENTITY cvs-rev "$Revision: 1.323 $">
+  <!ENTITY cvs-rev "$Revision: 1.324 $">
 
   <!-- if you are translating this document, please notate the CVS
        revision of the original developer's reference in cvs-en-rev -->
@@ -3928,6 +3928,59 @@ until that is available.
  <tt>/^  Homepage: [^ ]*$/</tt>,
  as this allows <file>packages.debian.org</file> to parse it correctly.</p>
         </sect1>
+
+        <sect1 id="bpp-vcs">
+          <heading>Version Control System location</heading>
+          <p>
+There are additional fields for the location of the Version Control System
+in <file>debian/control</file>.
+          <sect2><heading>XS-Vcs-Browser</heading>
+          <p>
+Value of this field should be a <tt>http://</tt> URL pointing to a
+web-browsable copy of the Version Control System repository used to
+maintain the given package, if available.
+          <p>
+The information is meant to be useful for the final user, willing to
+browse the latest work done on the package (e.g. when looking for the
+patch fixing a bug tagged as <tt>pending</tt> in the bug tracking
+system).
+          <sect2><heading>XS-Vcs-*</heading>
+          <p>
+Value of this field should be a string identifying unequivocally the
+location of the Version Control System repository used to maintain the
+given package, if available. <tt>*</tt> identify the Version Control
+System; currently the following systems are supported by the package
+tracking system: <tt>arch</tt>, <tt>bzr</tt> (Bazaar), <tt>cvs</tt>,
+<tt>darcs</tt>, <tt>git</tt>, <tt>hg</tt> (Mercurial), <tt>mtn</tt>
+(Monotone), <tt>svn</tt> (Subversion). It is allowed to specify different
+VCS fields for the same package: they will all be shown in the PTS web
+interface.
+          <p>
+The information is meant to be useful for a user knowledgeable in the
+given Version Control System and willing to build the current version of
+a package from the VCS sources. Other uses of this information might
+include automatic building of the latest VCS version of the given
+package. To this end the location pointed to by the field should better
+be version agnostic and point to the main branch (for VCSs supporting
+such a concept). Also, the location pointed to should be accessible to
+the final user; fulfilling this requirement might imply pointing to an
+anonymous access of the repository instead of pointing to an
+SSH-accessible version of the same.
+          <p>
+In the following example, an instance of the field for a Subversion
+repository of the <package>vim</package> package is shown. Note how the
+URL is in the <tt>svn://</tt> scheme (instead of <tt>svn+ssh://</tt>) and
+how it points to the <file>trunk/</file> branch. The use of the
+<tt>XS-Vcs-Browser</tt> field described above is also shown.
+<example>
+  Source: vim
+  Section: editors
+  Priority: optional
+  &lt;snip&gt;
+  XS-Vcs-Svn: svn://svn.debian.org/svn/pkg-vim/trunk/packages/vim
+  XS-Vcs-Browser: http://svn.debian.org/wsvn/pkg-vim/trunk/packages/vim
+</example>
+        </sect1>
       </sect>