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>[EMAIL PROTECTED]/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/[EMAIL PROTECTED]/libselinux?expand
+ </example>
+ A grab file looks like this:
+ <example>
+ Archive-Name: [EMAIL PROTECTED]
+ 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 <[EMAIL PROTECTED]> <http://www.golden-gryphon.com/>
1024D/BF24424C print 4966 F272 D093 B493 410B 924B 21BA DABB BF24 424C
