Debian Bug report logs - #391023
please document the Vcs-* field for describing package's version control system

version graph

Package: developers-reference; Maintainer for developers-reference is Developers Reference Maintainers <debian-policy@lists.debian.org>; Source for developers-reference is src:developers-reference.

Reported by: Stefano Zacchiroli <zack@debian.org>

Date: Wed, 4 Oct 2006 11:03:18 UTC

Severity: wishlist

Tags: patch

Found in version developers-reference/3.3.7

Fixed in version developers-reference/3.3.9

Done: debacle@debian.org (W. Martin Borgert)

Bug is archived. No further changes may be made.

Toggle useless messages

View this report as an mbox folder, status mbox, maintainer mbox


Report forwarded to debian-bugs-dist@lists.debian.org, Debian Documentation Project <debian-doc@lists.debian.org>:
Bug#391023; Package developers-reference. Full text and rfc822 format available.

Acknowledgement sent to Stefano Zacchiroli <zack@debian.org>:
New Bug report received and forwarded. Copy sent to Debian Documentation Project <debian-doc@lists.debian.org>. Full text and rfc822 format available.

Message #5 received at submit@bugs.debian.org (full text, mbox):

From: Stefano Zacchiroli <zack@debian.org>
To: Debian Bug Tracking System <submit@bugs.debian.org>
Subject: please document the Vcs-* field for describing package's version control system
Date: Wed, 04 Oct 2006 12:44:44 +0200
[Message part 1 (text/plain, inline)]
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
[developers_reference-vcs_field.patch (text/plain, attachment)]

Information forwarded to debian-bugs-dist@lists.debian.org, Debian Documentation Project <debian-doc@lists.debian.org>:
Bug#391023; Package developers-reference. Full text and rfc822 format available.

Acknowledgement sent to Manoj Srivastava <srivasta@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Documentation Project <debian-doc@lists.debian.org>. Full text and rfc822 format available.

Message #10 received at 391023@bugs.debian.org (full text, mbox):

From: Manoj Srivastava <srivasta@debian.org>
To: debian-devel@lists.debian.org
Subject: Re: XS-X-Vcs-XXX field not (yet) announced
Date: Thu, 05 Oct 2006 10:32:49 -0500
Hi,

        Coming back to what it would take to fully specify sources in
 an arch archive so that users can download the sources, I think that
 the best thing to use would be to provide a URL for a grab file. The
 grab file has a syntax:
,----
| Archive-Name: [the name of the archive]
| Archive-Location: [the location of the archive]
| Target-Revision: [PACKAGE|VERSION|REVISION to get]
| Target-Directory: [optional][The suggested directory to get into]
| Target-Config: [optional][A configuration to build upon grabbing]
`----

        I would also like to change the field name to  XS-VCS-Arch
 (tla is one implementation, baz is another, the VCS is called arch).

======================================================================
 XS-VCS-Arch: http://people.debian.org/~srivasta/grab-flex

__> cat grab-flex
Archive-Name: srivasta@debian.org--etch
Archive-Location: http://arch.debian.org/arch/private/srivasta
Target-Revision: packages--debian--0.1
Target-Directory: manoj-packages
Target-Config: configs/flex/debian/flex-2.5.33-9
__> tla grab http://people.debian.org/~srivasta/grab-flex
Grabbing: srivasta@debian.org--etch/http://arch.debian.org/arch/private/srivasta
Source: http://arch.debian.org/arch/private/srivasta, Dest: manoj-packages
Config: configs/flex/debian/flex-2.5.33-9
* from revision library: srivasta@debian.org--etch/packages--debian--0.1--patch-11
* ensuring library has srivasta@debian.org--etch/flex--devo--2.5.33--patch-4
* from revision library: srivasta@debian.org--etch/flex--devo--2.5.33--patch-4
* tree version set srivasta@debian.org--etch/flex--devo--2.5.33
* ensuring library has srivasta@debian.org--etch/debian-dir--flex--1.0--patch-29
* patching for this revision (srivasta@debian.org--etch/debian-dir--flex--1.0--patch-29)
* from revision library: srivasta@debian.org--etch/debian-dir--flex--1.0--patch-29
* tree version set srivasta@debian.org--etch/debian-dir--flex--1.0
* ensuring library has srivasta@debian.org--etch/skeleton-make-rules--main--0.1--patch-14
* from revision library: srivasta@debian.org--etch/skeleton-make-rules--main--0.1--patch-14
* tree version set srivasta@debian.org--etch/skeleton-make-rules--main--0.1
======================================================================


        manoj
-- 
I feel like I am sharing a ``CORN-DOG'' with NIKITA KHRUSCHEV ...
Manoj Srivastava <srivasta@debian.org> <http://www.debian.org/~srivasta/>
1024D/BF24424C print 4966 F272 D093 B493 410B  924B 21BA DABB BF24 424C



Information forwarded to debian-bugs-dist@lists.debian.org, Debian Documentation Project <debian-doc@lists.debian.org>:
Bug#391023; Package developers-reference. Full text and rfc822 format available.

Acknowledgement sent to Andreas Barth <aba@not.so.argh.org>:
Extra info received and forwarded to list. Copy sent to Debian Documentation Project <debian-doc@lists.debian.org>. Full text and rfc822 format available.

Message #15 received at 391023@bugs.debian.org (full text, mbox):

From: Andreas Barth <aba@not.so.argh.org>
To: debian-policy@lists.debian.org, debian-qa@lists.debian.org, 391023@bugs.debian.org
Subject: XS-Vcs-field
Date: Sun, 12 Nov 2006 09:58:50 +0100
Hi,

in bug #391023, this description of this field is given:
+    <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
+  &lt;snip&gt;
+  XS-Vcs-Svn: svn://svn.debian.org/svn/pkg-vim/trunk/packages/vim
+      </example>
+      </p>
+    </item>

Is this desciption correct?


Cheers,
Andi
-- 
  http://home.arcor.de/andreas-barth/



Information forwarded to debian-bugs-dist@lists.debian.org, Debian Documentation Project <debian-doc@lists.debian.org>:
Bug#391023; Package developers-reference. Full text and rfc822 format available.

Acknowledgement sent to stappers@stappers.nl (Geert Stappers):
Extra info received and forwarded to list. Copy sent to Debian Documentation Project <debian-doc@lists.debian.org>. Full text and rfc822 format available.

Message #20 received at 391023@bugs.debian.org (full text, mbox):

From: stappers@stappers.nl (Geert Stappers)
To: debian-policy@lists.debian.org, debian-qa@lists.debian.org, 391023@bugs.debian.org
Subject: Re: Bug#391023: XS-Vcs-field splitting into XS-Vcs-source & XS-Vcs-dpkg
Date: Sun, 12 Nov 2006 11:52:35 +0100
Op 12-11-2006 om 09:58 schreef Andreas Barth:
> Hi,
> 
> in bug #391023, this description of this field is given:
> +    <tag><tt>XS-Vcs-*</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>
> +      <example>
> +  XS-Vcs-Svn: svn://svn.debian.org/svn/pkg-vim/trunk/packages/vim
> +      </example>
> +      </p>
> 
> Is this desciption correct?


The description leafs room for ambiguity.

The text tells about the (upstream) source by using the generic name
"package", the example tells about the Debian directory.


Where I think the XS-Vcs field is a good thing,
I also think there should a field for the upstream source
and a field for the Debian packaging stuff.

So I propose to split into XS-Vcs-source-* & XS-Vcs-dpkg-*

It allows upstream and Debian packager to use different repositories,
that includes upstream having a version control system and the Debian
packager having no vcs.

Other advantage of it is that is allows to get to upstream stream
without the debian stuff.


Cheers
Geert Stappers



Information forwarded to debian-bugs-dist@lists.debian.org, Debian Documentation Project <debian-doc@lists.debian.org>:
Bug#391023; Package developers-reference. Full text and rfc822 format available.

Acknowledgement sent to Raphael Hertzog <hertzog@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Documentation Project <debian-doc@lists.debian.org>. Full text and rfc822 format available.

Message #25 received at 391023@bugs.debian.org (full text, mbox):

From: Raphael Hertzog <hertzog@debian.org>
To: Geert Stappers <stappers@stappers.nl>, 391023@bugs.debian.org
Cc: debian-policy@lists.debian.org, debian-qa@lists.debian.org
Subject: Re: Bug#391023: XS-Vcs-field splitting into XS-Vcs-source & XS-Vcs-dpkg
Date: Sun, 12 Nov 2006 15:04:14 +0100
On Sun, 12 Nov 2006, Geert Stappers wrote:
> The text tells about the (upstream) source by using the generic name
> "package", the example tells about the Debian directory.

So fix the wording... and don't change everything when there has been some
serious discussion on -devel and when lots of packages have started using
this convention already.

> So I propose to split into XS-Vcs-source-* & XS-Vcs-dpkg-*

Please, no. The Debian source package is not meant as a source of generic
meta-information of the upstream project.

If you really want to make this kind of information available, you'd
rather work on something useful for this like the collaborative repository
of meta-information:
http://wiki.debian.org/CRMI

(which might be implemented within mole http://wiki.debian.org/mole)

Cheers,
-- 
Raphaël Hertzog

Premier livre français sur Debian GNU/Linux :
http://www.ouaza.com/livre/admin-debian/



Information forwarded to debian-bugs-dist@lists.debian.org, Debian Documentation Project <debian-doc@lists.debian.org>:
Bug#391023; Package developers-reference. Full text and rfc822 format available.

Acknowledgement sent to Manoj Srivastava <srivasta@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Documentation Project <debian-doc@lists.debian.org>. Full text and rfc822 format available.

Message #30 received at 391023@bugs.debian.org (full text, mbox):

From: Manoj Srivastava <srivasta@debian.org>
To: Andreas Barth <aba@not.so.argh.org>
Cc: debian-policy@lists.debian.org, debian-qa@lists.debian.org, 391023@bugs.debian.org, debian-devel@lists.debian.org
Subject: Re: XS-Vcs-field
Date: Sun, 12 Nov 2006 14:02:58 -0600
Hi,

in bug #391023, this description of this field is given:
+    <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>

        tla is wrong. The name of the protocol is arch; and tla and
 baz are competing implementations of the standard.

+      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>

        I think this is a specification without adequate rationale and
 does not specify the use cases it is trying to meet.

        I can see two distinct requirements that users have: 
 a) Need to download the latest version
 b) need to browse the latest code.

        Both use cases seem to be equally important, and in my
 informal survey, seem to be equally used. Indeed, going to
 http://svn.debian.org/ and htttp://arch.debian.org/, we see that both
 the use cases are met on the web page: there is a svn:// address, as
 wells as a websvn pointer. Part of the confusion over the headers
 emerges from the problem that we are trying to overload both tasks on
 to one header.

        I suggest that we specify tow headers: and SCM specific
 header, XS-Vcs-<NAME> where name is one keyword from a specified list
 (bzr, cvs, svn, darcs, git, hf, or arch), and XS-VCS-Browse, which is
 a plain old HTTP URL.


,----[ Headers for the Flex package ]
|  XS-VCS-Arch: http://people.debian.org/~srivasta/grab-flex
|  XS-VCS-Browse: http://arch.debian.org/cgi-bin/archzoom.cgi/srivasta@debian.org--etch/flex?expand
`----

+      <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
+  &lt;snip&gt;
+  XS-Vcs-Svn: svn://svn.debian.org/svn/pkg-vim/trunk/packages/vim
+      </example>
+      </p>
+    </item>


                Coming back to what it would take to fully specify sources in
 an arch archive so that users can download the sources, I think that
 the best thing to use would be to provide a URL for a grab file. The
 grab file has a syntax:

,----
| Archive-Name: [the name of the archive]
| Archive-Location: [the location of the archive]
| Target-Revision: [PACKAGE|VERSION|REVISION to get]
| Target-Directory: [optional][The suggested directory to get into]
| Target-Config: [optional][A configuration to build upon grabbing]
`----

======================================================================
 XS-VCS-Arch: http://people.debian.org/~srivasta/grab-flex
 XS-VCS-Browse: http://arch.debian.org/cgi-bin/archzoom.cgi/srivasta@debian.org--etch/flex?expand

__> cat grab-flex
Archive-Name: srivasta@debian.org--etch
Archive-Location: http://arch.debian.org/arch/private/srivasta
Target-Revision: packages--debian--0.1
Target-Directory: manoj-packages
Target-Config: configs/flex/debian/flex-2.5.33-9
__> tla grab http://people.debian.org/~srivasta/grab-flex
Grabbing: srivasta@debian.org--etch/http://arch.debian.org/arch/private/srivasta
Source: http://arch.debian.org/arch/private/srivasta, Dest: manoj-packages
Config: configs/flex/debian/flex-2.5.33-9
* from revision library: srivasta@debian.org--etch/packages--debian--0.1--patch-
11
* ensuring library has srivasta@debian.org--etch/flex--devo--2.5.33--patch-4
* from revision library: srivasta@debian.org--etch/flex--devo--2.5.33--patch-4
* tree version set srivasta@debian.org--etch/flex--devo--2.5.33
* ensuring library has srivasta@debian.org--etch/debian-dir--flex--1.0--patch-29
* patching for this revision (srivasta@debian.org--etch/debian-dir--flex--1.0--p
atch-29)
* from revision library: srivasta@debian.org--etch/debian-dir--flex--1.0--patch-
29
* tree version set srivasta@debian.org--etch/debian-dir--flex--1.0
* ensuring library has srivasta@debian.org--etch/skeleton-make-rules--main--0.1-
-patch-14
* from revision library: srivasta@debian.org--etch/skeleton-make-rules--main--0.
1--patch-14
* tree version set srivasta@debian.org--etch/skeleton-make-rules--main--0.1
======================================================================

        manoj
-- 
Sometimes a cigar is just a cigar. Sigmund Freud
Manoj Srivastava <srivasta@debian.org> <http://www.debian.org/~srivasta/>
1024D/BF24424C print 4966 F272 D093 B493 410B  924B 21BA DABB BF24 424C



Information forwarded to debian-bugs-dist@lists.debian.org, Debian Documentation Project <debian-doc@lists.debian.org>:
Bug#391023; Package developers-reference. Full text and rfc822 format available.

Acknowledgement sent to stappers@stappers.nl (Geert Stappers):
Extra info received and forwarded to list. Copy sent to Debian Documentation Project <debian-doc@lists.debian.org>. Full text and rfc822 format available.

Message #35 received at 391023@bugs.debian.org (full text, mbox):

From: stappers@stappers.nl (Geert Stappers)
To: 391023@bugs.debian.org, debian-policy@lists.debian.org, debian-qa@lists.debian.org
Subject: Re: Bug#391023: XS-Vcs-field rewording
Date: Mon, 13 Nov 2006 00:07:05 +0100
Op 12-11-2006 om 15:04 schreef Raphael Hertzog:
> On Sun, 12 Nov 2006, Geert Stappers wrote:
> > The text tells about the (upstream) source by using the generic name
> > "package", the example tells about the Debian directory.
> 
> So fix the wording...

 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 Debian part of the 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

So:

Value of this field should be an URL pointing to where the repository of
the Debian part of the 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



HtH
GSt



Information forwarded to debian-bugs-dist@lists.debian.org, Debian Documentation Project <debian-doc@lists.debian.org>:
Bug#391023; Package developers-reference. Full text and rfc822 format available.

Acknowledgement sent to Clytie Siddall <clytie@riverland.net.au>:
Extra info received and forwarded to list. Copy sent to Debian Documentation Project <debian-doc@lists.debian.org>. Full text and rfc822 format available.

Message #40 received at 391023@bugs.debian.org (full text, mbox):

From: Clytie Siddall <clytie@riverland.net.au>
To: stappers@stappers.nl (Geert Stappers), 391023@bugs.debian.org
Subject: Re: Bug#391023: XS-Vcs-field rewording
Date: Mon, 13 Nov 2006 18:10:34 +1030
[Message part 1 (text/plain, inline)]
On 13/11/2006, at 9:37 AM, Geert Stappers wrote:

> Op 12-11-2006 om 15:04 schreef Raphael Hertzog:
>> On Sun, 12 Nov 2006, Geert Stappers wrote:
>>> The text tells about the (upstream) source by using the generic name
>>> "package", the example tells about the Debian directory.
>>
>> So fix the wording...
>
>  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 Debian part of the 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
>
> So:
>
> Value of this field should be an URL pointing to where the  
> repository of
> the Debian part of the 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

- an URL
+ a URL

from Clytie (vi-VN, Vietnamese free-software translation team / nhóm  
Việt hóa phần mềm tự do)
http://groups-beta.google.com/group/vi-VN
[PGP.sig (application/pgp-signature, inline)]

Information forwarded to debian-bugs-dist@lists.debian.org, Debian Documentation Project <debian-doc@lists.debian.org>:
Bug#391023; Package developers-reference. Full text and rfc822 format available.

Acknowledgement sent to Thijs Kinkhorst <thijs@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Documentation Project <debian-doc@lists.debian.org>. Full text and rfc822 format available.

Message #45 received at 391023@bugs.debian.org (full text, mbox):

From: Thijs Kinkhorst <thijs@debian.org>
To: debian-policy@lists.debian.org, debian-qa@lists.debian.org, 391023@bugs.debian.org, debian-devel@lists.debian.org
Subject: Re: XS-Vcs-field
Date: Mon, 13 Nov 2006 09:18:00 +0100
[Message part 1 (text/plain, inline)]
On Sun, 2006-11-12 at 14:02 -0600, Manoj Srivastava wrote:
>         I suggest that we specify tow headers: and SCM specific
>  header, XS-Vcs-<NAME> where name is one keyword from a specified list
>  (bzr, cvs, svn, darcs, git, hf, or arch), and XS-VCS-Browse, which is
>  a plain old HTTP URL.

Yes, this is what I'd like to see too (as per bug #393462). Since it
adds an extra header it doesn't break packages already using
XS-Vcs-<NAME>.


Thijs
[signature.asc (application/pgp-signature, inline)]

Information forwarded to debian-bugs-dist@lists.debian.org, Debian Documentation Project <debian-doc@lists.debian.org>:
Bug#391023; Package developers-reference. Full text and rfc822 format available.

Acknowledgement sent to Stefano Zacchiroli <zack@bononia.it>:
Extra info received and forwarded to list. Copy sent to Debian Documentation Project <debian-doc@lists.debian.org>. Full text and rfc822 format available.

Message #50 received at 391023@bugs.debian.org (full text, mbox):

From: Stefano Zacchiroli <zack@bononia.it>
To: Manoj Srivastava <srivasta@debian.org>
Cc: Andreas Barth <aba@not.so.argh.org>, debian-policy@lists.debian.org, debian-qa@lists.debian.org, 391023@bugs.debian.org, debian-devel@lists.debian.org
Subject: Re: XS-Vcs-field
Date: Mon, 13 Nov 2006 17:31:32 +0100
On dom, 2006-11-12 at 14:02 -0600, Manoj Srivastava wrote:
>         tla is wrong. The name of the protocol is arch; and tla and
>  baz are competing implementations of the standard.

Agreed, will fix this.

<snipped useful analysis>

>         I suggest that we specify tow headers: and SCM specific
>  header, XS-Vcs-<NAME> where name is one keyword from a specified list
>  (bzr, cvs, svn, darcs, git, hf, or arch), and XS-VCS-Browse, which is
>  a plain old HTTP URL.

I like this proposal and I will implement it (addressing other minor
issues pointed out by #393462).

>                 Coming back to what it would take to fully specify sources in
>  an arch archive so that users can download the sources, I think that
>  the best thing to use would be to provide a URL for a grab file. The
>  grab file has a syntax:

I don't have objections (mainly because I don't know what a grab file
is). More generally though I would like to know opinions about whether
it would be the case to describe in the developers reference what is the
appropriate (non-browse) url for a given VCS. For example, would it be
appropriate to document there that for arch a grab file should be used? 

Alternatively the description in the devref should remain vague
(something like "an url pointing to a resource allowing automatic
download of a debian source package") and a best practice section
(either in the devref or on the wiki) should be set up documenting how
to deal with the various VCS.

Thanks for your feedback,
Cheers.

-- 
Stefano Zacchiroli -*- Computer Science PhD student @ Uny Bologna, Italy
zack@{cs.unibo.it,debian.org,bononia.it} -%- http://www.bononia.it/zack/
(15:56:48)  Zack: e la demo dema ?    /\    All one has to do is hit the
(15:57:15)  Bac: no, la demo scema    \/    right keys at the right time



Information forwarded to debian-bugs-dist@lists.debian.org, Debian Documentation Project <debian-doc@lists.debian.org>:
Bug#391023; Package developers-reference. Full text and rfc822 format available.

Acknowledgement sent to Manoj Srivastava <srivasta@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Documentation Project <debian-doc@lists.debian.org>. Full text and rfc822 format available.

Message #55 received at 391023@bugs.debian.org (full text, mbox):

From: Manoj Srivastava <srivasta@debian.org>
To: debian-policy@lists.debian.org, debian-qa@lists.debian.org, 391023@bugs.debian.org
Subject: Re: XS-Vcs-field
Date: Tue, 14 Nov 2006 12:57:46 -0600
On Mon, 13 Nov 2006 17:31:32 +0100, Stefano Zacchiroli <zack@bononia.it> said: 

> On dom, 2006-11-12 at 14:02 -0600, Manoj Srivastava wrote:
>> I suggest that we specify tow headers: and SCM specific header,
>> XS-Vcs-<NAME> where name is one keyword from a specified list (bzr,
>> cvs, svn, darcs, git, hf, or arch), and XS-VCS-Browse, which is a
>> plain old HTTP URL.

> I like this proposal and I will implement it (addressing other minor
> issues pointed out by #393462).

>> Coming back to what it would take to fully specify sources in an
>> arch archive so that users can download the sources, I think that
>> the best thing to use would be to provide a URL for a grab
>> file. The grab file has a syntax:
> I don't have objections (mainly because I don't know what a grab
> file is). More generally though I would like to know opinions about
> whether it would be the case to describe in the developers reference
> what is the appropriate (non-browse) url for a given VCS. For
> example, would it be appropriate to document there that for arch a
> grab file should be used?

        I think so.  I can think of no other mechanism that would
 allow complex arch setups to be downloaded in a supported manner
 (simple single branch packages have alternate methods); and tla
 already supports using grab files.

        Arch, perhaps because it is a distributed SCM, and partially
 because different people take ownership of different 
 segments in a large project, tends to encourage proliferation of
 branches. A single project can be cobbled together from multiple
 repositories/branches, with perhaps multiple alternatives for each
 (this is in contrast with SVN, which does not really have a concept
 of a package, but servers up whatever you put in, and so the top
 level of a package can have everything -- much to a novices chagrin
 :)

        grab files can handle package/repo/branch mapping of arbitrary
 complexity. 

        Debian packages tend to be especially suited for multiple
 branches; since while most of the software is upstream, and is under
 the control of the upstream author, ./debian directories are created
 by the maintainer.  A grab file works like an arch config file; it
 helps stitch together a package  from the components.

        A grab file is also fairly static, and can be automatically
 updated using arch hooks, scp, and a simple shell script (I already
 have a hook function that updates the arch files whenever I commit
 ./debian; updating grab files is just an scp call away) .

        All the ./debian directories in all my packages have far more
 in common with each other than with the upstream sources they
 package; and changes to one of my ./debian dirs, to, say, add
 debsums, can be rapidly propagated to the sibling ./debian dirs; so
 it makes sense for the ./debian dirs to be branches of a debian-dir
 package.

        Or take emacs. I have a ./debian dir that can take CVS emacs
 and package it up for debian; but I can use the upstream mainline,
 the unicode branch, the multi-tty branch (which is my current), Miles
 Bader's branch, the lexbind branch, the tiling branch.

        So, one can mix and match upstream and debian dirs (Romain
 used to have his own  emacs-snapshot debian-dir repo somewhere)

        manoj

-- 
Boys will be boys, and so will a lot of middle-aged men. Kin Hubbard
Manoj Srivastava <srivasta@debian.org> <http://www.debian.org/~srivasta/>
1024D/BF24424C print 4966 F272 D093 B493 410B  924B 21BA DABB BF24 424C



Information forwarded to debian-bugs-dist@lists.debian.org, Debian Documentation Project <debian-doc@lists.debian.org>:
Bug#391023; Package developers-reference. Full text and rfc822 format available.

Acknowledgement sent to Stefano Zacchiroli <zack@bononia.it>:
Extra info received and forwarded to list. Copy sent to Debian Documentation Project <debian-doc@lists.debian.org>. Full text and rfc822 format available.

Message #60 received at 391023@bugs.debian.org (full text, mbox):

From: Stefano Zacchiroli <zack@bononia.it>
To: debian-devel@lists.debian.org
Cc: 391023@bugs.debian.org
Subject: Re: XS-Vcs-field
Date: Wed, 15 Nov 2006 18:13:52 +0100
[ added bug the bts as Cc ]

On mar, 2006-11-14 at 12:55 -0600, Manoj Srivastava wrote:
> > I don't have objections (mainly because I don't know what a grab
> > file is). More generally though I would like to know opinions about
> > whether it would be the case to describe in the developers reference
> > what is the appropriate (non-browse) url for a given VCS. For
> > example, would it be appropriate to document there that for arch a
> > grab file should be used?
> 
>         I think so.  I can think of no other mechanism that would
<snip>

I think you misread my question. I was not asking if a grab file is
appropriate as url target for arch, I believe you in this given that I'm
not an arch expert.

My question was wheter it would be appropriate to document in the devref
the choices of where the URL for a given VCS should point to or not? In
your case, do you want to see written in the devref "URLs for the Arch
VCS should point to a grab file"? Or would you prefer to leave such
choices to best practices or see them documented elsewhere?

Cheers.

-- 
Stefano Zacchiroli -*- Computer Science PhD student @ Uny Bologna, Italy
zack@{cs.unibo.it,debian.org,bononia.it} -%- http://www.bononia.it/zack/
(15:56:48)  Zack: e la demo dema ?    /\    All one has to do is hit the
(15:57:15)  Bac: no, la demo scema    \/    right keys at the right time



Information forwarded to debian-bugs-dist@lists.debian.org, Debian Documentation Project <debian-doc@lists.debian.org>:
Bug#391023; Package developers-reference. Full text and rfc822 format available.

Acknowledgement sent to Stefano Zacchiroli <zack@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Documentation Project <debian-doc@lists.debian.org>. Full text and rfc822 format available.

Message #65 received at 391023@bugs.debian.org (full text, mbox):

From: Stefano Zacchiroli <zack@debian.org>
To: 391023@bugs.debian.org
Subject: new version of the patch (documenting XS-Vcs-Browser as well)
Date: Mon, 19 Feb 2007 10:44:07 +0100
[Message part 1 (text/plain, inline)]
On Wed, Oct 04, 2006 at 12:44:44PM +0200, Stefano Zacchiroli wrote:
> The attached patch for the developers reference document the support for
> the Vcs-* family of fields.

I attach a new version of the patch for the developer's reference.

The main change from the previous patch is that now two fields are
supported: XS-Vcs-Browser (for a browsable version of the repository)
and XS-Vcs-* (same semantics as before).  I also implemented some of the
other comments received in this bug report and in past threads on
-devel.

Re-reading from a native English speaker would be really appreciated.

Could you please apply the patch?

Many thanks in advance,
Cheers.

-- 
Stefano Zacchiroli -*- Computer Science PhD student @ Uny Bologna, Italy
zack@{cs.unibo.it,debian.org,bononia.it} -%- http://www.bononia.it/zack/
(15:56:48)  Zack: e la demo dema ?    /\    All one has to do is hit the
(15:57:15)  Bac: no, la demo scema    \/    right keys at the right time
[developers_reference-vcs_field.patch (text/x-diff, attachment)]
[signature.asc (application/pgp-signature, inline)]

Information forwarded to debian-bugs-dist@lists.debian.org, Debian Documentation Project <debian-doc@lists.debian.org>:
Bug#391023; Package developers-reference. Full text and rfc822 format available.

Acknowledgement sent to Justin Pryzby <justinpryzby@users.sourceforge.net>:
Extra info received and forwarded to list. Copy sent to Debian Documentation Project <debian-doc@lists.debian.org>. Full text and rfc822 format available.

Message #70 received at 391023@bugs.debian.org (full text, mbox):

From: Justin Pryzby <justinpryzby@users.sourceforge.net>
To: Stefano Zacchiroli <zack@debian.org>, 391023@bugs.debian.org
Subject: Re: Bug#391023: new version of the patch (documenting XS-Vcs-Browser as well)
Date: Mon, 19 Feb 2007 05:50:29 -0500
On Mon, Feb 19, 2007 at 10:44:07AM +0100, Stefano Zacchiroli wrote:
> On Wed, Oct 04, 2006 at 12:44:44PM +0200, Stefano Zacchiroli wrote:
> > The attached patch for the developers reference document the support for
> > the Vcs-* family of fields.
> 
> I attach a new version of the patch for the developer's reference.
> 
> The main change from the previous patch is that now two fields are
> supported: XS-Vcs-Browser (for a browsable version of the repository)
> and XS-Vcs-* (same semantics as before).  I also implemented some of the
> other comments received in this bug report and in past threads on
> -devel.
> 
> Re-reading from a native English speaker would be really appreciated.
It looks good to me with the changes below.

Cheers
Justin

> +      <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 fixinv a bug tagged as <tt>pending</tt> in the bug tracking
               ^^^^^^
               fixing

> +      system).

> +      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
               ^^^
Consider using a semicolon or period.

> +      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
                      ^^^
Consider using a semicolon or period.



Information forwarded to debian-bugs-dist@lists.debian.org, Debian Documentation Project <debian-doc@lists.debian.org>:
Bug#391023; Package developers-reference. Full text and rfc822 format available.

Acknowledgement sent to Stefano Zacchiroli <zack@bononia.it>:
Extra info received and forwarded to list. Copy sent to Debian Documentation Project <debian-doc@lists.debian.org>. Full text and rfc822 format available.

Message #75 received at 391023@bugs.debian.org (full text, mbox):

From: Stefano Zacchiroli <zack@bononia.it>
To: Justin Pryzby <justinpryzby@users.sourceforge.net>
Cc: 391023@bugs.debian.org
Subject: Re: Bug#391023: new version of the patch (documenting XS-Vcs-Browser as well)
Date: Mon, 19 Feb 2007 13:57:55 +0100
[Message part 1 (text/plain, inline)]
On Mon, Feb 19, 2007 at 05:50:29AM -0500, Justin Pryzby wrote:
> It looks good to me with the changes below.

Thanks!

New version of the patch implementing your changes is attached.

Cheers.

-- 
Stefano Zacchiroli -*- Computer Science PhD student @ Uny Bologna, Italy
zack@{cs.unibo.it,debian.org,bononia.it} -%- http://www.bononia.it/zack/
(15:56:48)  Zack: e la demo dema ?    /\    All one has to do is hit the
(15:57:15)  Bac: no, la demo scema    \/    right keys at the right time
[developers_reference-vcs_field.patch (text/x-diff, attachment)]

Information forwarded to debian-bugs-dist@lists.debian.org, Debian Documentation Project <debian-doc@lists.debian.org>:
Bug#391023; Package developers-reference. Full text and rfc822 format available.

Acknowledgement sent to Manoj Srivastava <srivasta@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Documentation Project <debian-doc@lists.debian.org>. Full text and rfc822 format available.

Message #80 received at 391023@bugs.debian.org (full text, mbox):

From: Manoj Srivastava <srivasta@debian.org>
To: debian-devel@lists.debian.org
Cc: debian-policy@lists.debian.org, debian-qa@lists.debian.org, 391023@bugs.debian.org
Subject: Re: XS-Vcs-field
Date: Tue, 08 May 2007 14:13:56 -0500
[Message part 1 (text/plain, inline)]
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-vcs_field_new.patch (text/x-diff, inline)]
--- 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ël Hertzog
+      <author>Raphaël Hertzog
       <author>Christian Schwarz
       <author>Ian Jackson
       <version>ver. &version;, &date-en;
@@ -35,7 +35,7 @@
 	<copyrightsummary>
 copyright &copy; 1998&mdash;2003 Adam Di Carlo</copyrightsummary>
 	<copyrightsummary>
-copyright &copy; 2002&mdash;2003 Raphaël Hertzog</copyrightsummary>
+copyright &copy; 2002&mdash;2003 Raphaël Hertzog</copyrightsummary>
 	<copyrightsummary>
 copyright &copy; 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
+  &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 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>
[Message part 3 (text/plain, inline)]
-- 
"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

Information forwarded to debian-bugs-dist@lists.debian.org, Debian Documentation Project <debian-doc@lists.debian.org>:
Bug#391023; Package developers-reference. Full text and rfc822 format available.

Acknowledgement sent to Stefano Zacchiroli <zack@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Documentation Project <debian-doc@lists.debian.org>. Full text and rfc822 format available.

Message #85 received at 391023@bugs.debian.org (full text, mbox):

From: Stefano Zacchiroli <zack@debian.org>
To: Manoj Srivastava <srivasta@debian.org>
Cc: debian-devel@lists.debian.org, debian-policy@lists.debian.org, debian-qa@lists.debian.org, 391023@bugs.debian.org
Subject: Re: XS-Vcs-field
Date: Wed, 9 May 2007 00:07:26 +0200
[Message part 1 (text/plain, inline)]
On Tue, May 08, 2007 at 02:13:56PM -0500, Manoj Srivastava wrote:
>         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.

No object from me, just a suggestion for your arch example. In case
there exists some kind of web browsing possibility for an arch category
of for an arch grab file you can add XS-Vcs-Browser to your example as
well and uniform it with the preceding Subversion example.

> +         As another example, if the VCS being used is <tt>arch</tt>,
> +         the corresponding field anme would be:
                                    ^^^^
                                  typo here

Thanks for taking care of this,
Cheers.

-- 
Stefano Zacchiroli -*- PhD in Computer Science ............... now what?
zack@{cs.unibo.it,debian.org,bononia.it} -%- http://www.bononia.it/zack/
(15:56:48)  Zack: e la demo dema ?    /\    All one has to do is hit the
(15:57:15)  Bac: no, la demo scema    \/    right keys at the right time
[signature.asc (application/pgp-signature, inline)]

Information forwarded to debian-bugs-dist@lists.debian.org, Debian Documentation Project <debian-doc@lists.debian.org>:
Bug#391023; Package developers-reference. Full text and rfc822 format available.

Acknowledgement sent to Manoj Srivastava <srivasta@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Documentation Project <debian-doc@lists.debian.org>. Full text and rfc822 format available.

Message #90 received at 391023@bugs.debian.org (full text, mbox):

From: Manoj Srivastava <srivasta@debian.org>
To: debian-devel@lists.debian.org
Cc: debian-policy@lists.debian.org, debian-qa@lists.debian.org, 391023@bugs.debian.org
Subject: Re: XS-Vcs-field
Date: Tue, 08 May 2007 17:57:23 -0500
On Wed, 9 May 2007 00:07:26 +0200, Stefano Zacchiroli <zack@debian.org> said: 

> On Tue, May 08, 2007 at 02:13:56PM -0500, Manoj Srivastava wrote:
>> 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.

> No object from me, just a suggestion for your arch example. In case
> there exists some kind of web browsing possibility for an arch
> category of for an arch grab file you can add XS-Vcs-Browser to your
> example as well and uniform it with the preceding Subversion example.

        Umm, sure. I had not given an example of the control file, since
 that was the same as the control file for vim. Perhaps I need to make
 this more explicit, since you were confused. 

        http://packages.qa.debian.org/libs/libselinux.html corresponds
 to the following:
,----[ Source stanza of libselinux control file ]
| Source: libselinux
| XS-VCS-Arch: http://arch.debian.org/arch/private/srivasta/grab/libselinux
| XS-VCS-Browse: http://arch.debian.org/cgi-bin/archzoom.cgi/srivasta@debian.org--lenny/libselinux?expand
| Priority: optional
| Section: libs
| Maintainer: Manoj Srivastava <srivasta@debian.org>
| Standards-Version: 3.7.2.0
| Build-Depends: file, libsepol1-dev (>= 2.0.3), python-all-dev (>= 2.3.5-11), swig
| XS-Python-Version: >= 2.4
`----

>> + As another example, if the VCS being used is <tt>arch</tt>,
>> + the corresponding field anme would be:
>                            ^^^^
>                            typo here

        Thanks, fixed here.  I'll wait for a few more comments, and
 then I'll refresh the patch.

        manoj
-- 
Pray to God, but keep rowing to shore. Russian Proverb
Manoj Srivastava <srivasta@debian.org> <http://www.debian.org/~srivasta/>
1024D/BF24424C print 4966 F272 D093 B493 410B  924B 21BA DABB BF24 424C



Information forwarded to debian-bugs-dist@lists.debian.org, Debian Documentation Project <debian-doc@lists.debian.org>:
Bug#391023; Package developers-reference. Full text and rfc822 format available.

Acknowledgement sent to Manoj Srivastava <srivasta@golden-gryphon.com>:
Extra info received and forwarded to list. Copy sent to Debian Documentation Project <debian-doc@lists.debian.org>. Full text and rfc822 format available.

Message #95 received at 391023@bugs.debian.org (full text, mbox):

From: Manoj Srivastava <srivasta@golden-gryphon.com>
To: 391023@bugs.debian.org
Subject: XS-Vcs-field
Date: Tue, 22 May 2007 12:36:49 -0500
[Message part 1 (text/plain, inline)]
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

[developers_reference-vcs_field_new.patch (text/x-diff, inline)]
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
 	<p>
 A QA (quality assurance) web portal is available at <url
[Message part 3 (text/plain, inline)]
-- 
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

Tags added: pending Request was from Andreas Barth <aba@not.so.argh.org> to control@bugs.debian.org. (Sat, 16 Jun 2007 21:43:19 GMT) Full text and rfc822 format available.

Information forwarded to debian-bugs-dist@lists.debian.org, Debian Documentation Project <debian-doc@lists.debian.org>:
Bug#391023; Package developers-reference. Full text and rfc822 format available.

Acknowledgement sent to Guillem Jover <guillem@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Documentation Project <debian-doc@lists.debian.org>. Full text and rfc822 format available.

Message #102 received at 391023@bugs.debian.org (full text, mbox):

From: Guillem Jover <guillem@debian.org>
To: Manoj Srivastava <srivasta@golden-gryphon.com>
Cc: 391023@bugs.debian.org
Subject: Re: XS-Vcs-field
Date: Thu, 4 Oct 2007 04:35:19 +0300
[Message part 1 (text/plain, inline)]
Hi,

On Tue, 2007-05-22 at 12:36:49 -0500, Manoj Srivastava wrote:
>         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.

I'm attaching a patch on top of Manoj's, which documents the field w/o
the XS- prefix. Those fields are now supported in dpkg since 1.14.6.

regards,
guillem
[ddp-devref_vcs-field.patch (text/x-diff, attachment)]

Reply sent to debacle@debian.org (W. Martin Borgert):
You have taken responsibility. Full text and rfc822 format available.

Notification sent to Stefano Zacchiroli <zack@debian.org>:
Bug acknowledged by developer. Full text and rfc822 format available.

Message #107 received at 391023-close@bugs.debian.org (full text, mbox):

From: debacle@debian.org (W. Martin Borgert)
To: 391023-close@bugs.debian.org
Subject: Bug#391023: fixed in developers-reference 3.3.9
Date: Thu, 28 Feb 2008 11:47:02 +0000
Source: developers-reference
Source-Version: 3.3.9

We believe that the bug you reported is fixed in the latest version of
developers-reference, which is due to be installed in the Debian FTP archive:

developers-reference-fr_3.3.9_all.deb
  to pool/main/d/developers-reference/developers-reference-fr_3.3.9_all.deb
developers-reference_3.3.9.dsc
  to pool/main/d/developers-reference/developers-reference_3.3.9.dsc
developers-reference_3.3.9.tar.gz
  to pool/main/d/developers-reference/developers-reference_3.3.9.tar.gz
developers-reference_3.3.9_all.deb
  to pool/main/d/developers-reference/developers-reference_3.3.9_all.deb



A summary of the changes between this version and the previous one is
attached.

Thank you for reporting the bug, which will now be closed.  If you
have further comments please address them to 391023@bugs.debian.org,
and the maintainer will reopen the bug report if appropriate.

Debian distribution maintenance software
pp.
W. Martin Borgert <debacle@debian.org> (supplier of updated developers-reference package)

(This message was generated automatically at their request; if you
believe that there is a problem with it please contact the archive
administrators by mailing ftpmaster@debian.org)


-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Format: 1.7
Date: Thu, 28 Feb 2008 10:16:40 +0000
Source: developers-reference
Binary: developers-reference developers-reference-fr
Architecture: source all
Version: 3.3.9
Distribution: unstable
Urgency: low
Maintainer: Debian Documentation Project <debian-doc@lists.debian.org>
Changed-By: W. Martin Borgert <debacle@debian.org>
Description: 
 developers-reference - guidelines and information for Debian developers
 developers-reference-fr - guidelines and information for Debian developers, in French
Closes: 356720 373816 374220 384178 391023 401415 405453 405818 410159 412757 413320 414291 419507 420540 422750 427832 428846 445642
Changes: 
 developers-reference (3.3.9) unstable; urgency=low
 .
   [ Andreas Barth ]
   * Packaging changes:
     - bump standards-version to 3.7.3 (no change)
     - fix debian/copyright
     - move debhelper to Build-Depends.
     - add pdf for French version.
   * Document changes to stable release management. Closes: #414291
   * Debconf error templates no longer discouraged. Thanks,
     Christian Perrier. Closes: #427832
   * Keyring now uses RT. Closes: #428846
   * Document -dbg-packages within BPs. Thanks, Joey Hess. Closes: #420540
   * NMUs now also close bugs. Thanks, Lucas Nussbaum. Closes: #419507
   * Fix documentation about gender neutral. Closes: #384178
   * Fix typo. Closes: #405453
   * More details on how to write documentation. Thanks, Josh Triplett.
     Closes: #422750
   * Add XS-Vcs-*. Thanks to Stefano Zacchiroli. Closes: #391023
   * Small brushup to debconf description. Thanks, Thomas Huriaux.
     Closes: #401415
   * Document Team-Maintainence better. Thanks, Lucas Nussbaum.
     Closes: #410159
   * Add link to more removal ressources. Thanks, Adam D. Barratt,
     Justin Pryzby. Closes: #412757, #356720
   * Repacking source packages need to be documented in copyright.
     Thanks, Russ Allbery. Closes: #413320
   * Better describe version of debian native packages NMUs. Closes: #405818
   * Source, HTML and text are now encoded in UTF-8. Thanks, Jörg Sommer.
     Closes: #373816
   * Source is now DocBook XML instead of debiandoc. Closes: #374220
 .
   [ Raphael Hertzog ]
   * Add a link to enrico's excellent Debian Community Guidelines.
   * Recommend the use of DSA's request tracker instead of mailing them.
   * Remove reference to #debian-sf, #debian-bsd which don't exist anymore. Put
     a reference to #debian-dpkg instead.
   * Remove all stuff concerning non-US.
   * Update information concerning Alioth.
   * Update information concerning the Package Tracking System.
   * Mention Alioth as the main resource for VCS repositories and deprecate
     cvs.debian.org.
   * Remove XS- prefix for Vcs-* fields since dpkg now supports them.
   * Document the Homepage field. Thanks, Christian Perrier. Closes:
     #445642
   * Add Vcs-Svn and Vcs-Browser fields pointing to the new SVN
     repository.
Files: 
 f3b140613997b6255f00cff2e0652485 866 doc optional developers-reference_3.3.9.dsc
 feb746b3608063b4994472866f39709e 871922 doc optional developers-reference_3.3.9.tar.gz
 4f4292fe8246f1338115266a7ff61349 660596 doc optional developers-reference_3.3.9_all.deb
 72e49ae1cd934ebaaf411beb7852214d 663386 doc optional developers-reference-fr_3.3.9_all.deb

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.6 (GNU/Linux)

iD8DBQFHxpwF+xM0OFfj6IgRAqdfAJwNNiihs+QYn2KuGIFWNz4UbU0rYACZATqP
VNJKCAzzbxObVoiWSiSsPDY=
=9TZe
-----END PGP SIGNATURE-----





Bug archived. Request was from Debbugs Internal Request <owner@bugs.debian.org> to internal_control@bugs.debian.org. (Tue, 08 Apr 2008 07:31:48 GMT) Full text and rfc822 format available.

Send a report that this bug log contains spam.


Debian bug tracking system administrator <owner@bugs.debian.org>. Last modified: Sun Apr 20 00:18:09 2014; Machine Name: buxtehude.debian.org

Debian Bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.