Re: XS-Vcs-field
Hi,
It has been a long time since there was any discussion on this.
I have taken the last patch created by Stefano Zacchiroli, added an
arch specific example, regenerated the patch against todays CVS of the
developers reference, and attached it to this mail.
The PTS already implements the fields referred to in this patch,
so this is a working current practice, and I think we are way past the
design phase, so there should be no objection to including this in the
developers reference.
manoj
--- developers-reference/developers-reference.sgml 2006-11-12 05:05:22.000000000 -0600
+++ developers-reference.new/developers-reference.sgml 2007-05-08 14:05:28.000000000 -0500
@@ -24,7 +24,7 @@
<author>Developer's Reference Team &email-devel-ref;
<author>Andreas Barth
<author>Adam Di Carlo
- <author>Rapha�Hertzog
+ <author>Rapha�Hertzog
<author>Christian Schwarz
<author>Ian Jackson
<version>ver. &version;, &date-en;
@@ -35,7 +35,7 @@
<copyrightsummary>
copyright © 1998—2003 Adam Di Carlo</copyrightsummary>
<copyrightsummary>
-copyright © 2002—2003 Rapha�Hertzog</copyrightsummary>
+copyright © 2002—2003 Rapha�Hertzog</copyrightsummary>
<copyrightsummary>
copyright © 1997, 1998 Christian Schwarz</copyrightsummary>
<p>
@@ -1565,6 +1565,102 @@
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-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 anme 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>
+ 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>
--
"The most incomprehensible thing about the world is that it is
comprehensible." Albert Einstein : Understanding the world
Manoj Srivastava <srivasta@debian.org> <http://www.debian.org/~srivasta/>
1024D/BF24424C print 4966 F272 D093 B493 410B 924B 21BA DABB BF24 424C
Reply to: