Bug#391023: please document the Vcs-* field for describing package's version control system
Package: developers-reference
Version: 3.3.7
Severity: wishlist
Tags: patch
The PTS web interface now support displaying of information carried in
Source packages via "XS-" fields. At the moment it supports the
rendering of the information carried by the family of fields Vcs-*,
where "*" is a tag referring to the most popular version control
systems. For a preview of this feature you can have a look at the PTS
page of vim [1]. More information are available in a blog post of mine
on planet [2].
According to some discussion on debian-devel and to the fact that
several people started adding the field, it seems that this kind of
information is appreciated by DDs and it should be properly documented
in the developers reference, which already document the other features
of the PTS.
The attached patch for the developers reference document the support for
the Vcs-* family of fields.
Could you please review it and possibly apply to the developers
reference package?
Many thanks in advance,
Cheers.
[1] http://packages.qa.debian.org/v/vim.html
[2] http://www.bononia.it/~zack/blog/posts/xs-x-vcs-XXX.html
-- System Information:
Debian Release: testing/unstable
APT prefers unstable
APT policy: (500, 'unstable'), (500, 'testing')
Architecture: i386 (i686)
Shell: /bin/sh linked to /bin/bash
Kernel: Linux 2.6.18-aquarium
Locale: LANG=it_IT.UTF-8, LC_CTYPE=it_IT.UTF-8 (charmap=UTF-8)
developers-reference depends on no packages.
Versions of packages developers-reference recommends:
ii debian-policy 3.7.2.1 Debian Policy Manual and related d
-- no debconf information
diff -ur developers-reference-3.3.7.orig/developers-reference.sgml developers-reference-3.3.7/developers-reference.sgml
--- developers-reference-3.3.7.orig/developers-reference.sgml 2006-10-01 14:03:59.000000000 +0200
+++ developers-reference-3.3.7/developers-reference.sgml 2006-10-01 14:52:06.000000000 +0200
@@ -1535,6 +1535,47 @@
to remove it later and you won't be able to edit it either. The only thing
that you can do is send a second news item that will deprecate the
information contained in the previous one.
+
+ <sect2 id="pts-web-fields">Extra information shown in the PTS web interface
+ <p>
+ In addition to the information discussed above, the PTS web interface shows
+ information available in source packages as <em>extra source fields</em>
+ (i.e. fields starting with <tt>XS-</tt> in source package control files). The
+ following fields are currently supported:
+ <taglist>
+ <tag><tt>XS-Vcs-*</tt>
+ <item>
+ (where <em>Vcs</em> is the acronym for <em>Version Control System</em>,
+ and <tt>*</tt> stands for one of the Vcs supported by the package
+ tracking system: <tt>bzr</tt>, <tt>cvs</tt>, <tt>darcs</tt>,
+ <tt>git</tt>, <tt>hg</tt>, <tt>svn</tt>, <tt>tla</tt>)
+ <p>
+ Value of this field should be an URL pointing to where the repository of
+ the given package is available. The information is meant to be useful for
+ the final user of the package in case he is looking for the latest work
+ done on the package (e.g. for the patch fixing a bug tagged as
+ <tt>pending</tt> in the bug tracking system). The URL should be meaningful
+ for the given Vcs and should better be version agnostic. If possible, the
+ URL should point to a resource accessible to the final user and from which
+ the latest repository snapshot can be easily obtained.
+ </p>
+ <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.
+ <example>
+ Source: vim
+ Section: editors
+ Priority: optional
+ <snip>
+ XS-Vcs-Svn: svn://svn.debian.org/svn/pkg-vim/trunk/packages/vim
+ </example>
+ </p>
+ </item>
+ </taglist>
+ </p>
+ </sect2>
<sect id="ddpo">Developer's packages overview
<p>
Reply to: