[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Bug#391023: XS-Vcs-field


        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.


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
+  &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>
+      </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
+  &lt;snip&gt;
+ 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
 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: