Bug#391023: XS-Vcs-field
Hi,
The following patch has been reworked with additional
discussion on the mailing list. It supersedes are previous patches, and
incorporates material from everything earlier in the bug report.
manoj
diff -uBbwr developers-reference.orig/developers-reference.sgml developers-reference/developers-reference.sgml
--- developers-reference.orig/developers-reference.sgml 2006-11-12 05:05:22.000000000 -0600
+++ developers-reference/developers-reference.sgml 2007-05-22 12:33:32.000000000 -0500
@@ -1566,6 +1566,110 @@
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-Browser<tt>
+ <item>
+ <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>
+ <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).
+ </p>
+ </item>
+ <tag><tt>XS-Vcs-*</tt>
+ <item>
+ <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>
+ <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>
+ <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
+ <snip>
+ 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>
+ </p>
+ <p>
+ As another example, if the VCS being used is <tt>arch</tt>,
+ the corresponding field name would be:
+ <strong>XS-VCS-Arch</strong>. The value for the field
+ depends on how the package is composed from the VCS:
+ <enumlist>
+ <item>
+ <p>If the sources live in a single <tt>arch</tt>
+ <em>category</em>, then the value is the location for
+ the category: <tt>dev@foo.org--2007/pkg--devo--1.0</tt></p>
+ </item>
+ <item>
+ <p>
+ If the package is composed of a number of <tt>arch</tt>
+ <em>categories</em>, then a <em>grab</em> file should
+ be used.
+ </p>
+ </item>
+ </enumlist>
+ <example>
+ Source: libselinux
+ Priority: optional
+ Section: libs
+ <snip>
+ XS-VCS-Arch: http://arch.debian.org/arch/private/srivasta/grab/libselinux
+ XS-VCS-Browser: http://arch.debian.org/cgi-bin/archzoom.cgi/srivasta@debian.org--lenny/libselinux?expand
+ </example>
+ A grab file looks like this:
+ <example>
+ Archive-Name: srivasta@debian.org--lenny
+ Archive-Location: http://arch.debian.org/arch/private/srivasta
+ Target-Revision: packages--debian--1.0
+ Target-Directory: manoj-packages
+ Target-Config: configs/libselinux/debian/libselinux-2.0.15-2
+ </example>
+ In either case, <tt>baz get <em>contents of XS-VCS-Arch</em></tt>
+ should checkout the latest version the package.
+ </p>
+ </item>
+ </taglist>
+ </p>
+ </sect2>
+
<sect id="ddpo">Developer's packages overview
<p>
A QA (quality assurance) web portal is available at <url
--
Never offend people with style when you can offend them with
substance. Sam Brown, "The Washington Post", January 26, 1977
Manoj Srivastava <srivasta@acm.org> <http://www.golden-gryphon.com/>
1024D/BF24424C print 4966 F272 D093 B493 410B 924B 21BA DABB BF24 424C
Reply to: