Debian Bug report logs - #654958
debian-policy: Document VCS fields.

version graph

Package: debian-policy; Maintainer for debian-policy is Debian Policy List <debian-policy@lists.debian.org>; Source for debian-policy is src:debian-policy.

Reported by: Charles Plessy <plessy@debian.org>

Date: Sat, 7 Jan 2012 06:15:02 UTC

Severity: normal

Found in version debian-policy/3.9.2.0

Fixed in version debian-policy/3.9.4.0

Done: Russ Allbery <rra@debian.org>

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, plessy@debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#654958; Package debian-policy. (Sat, 07 Jan 2012 06:15:05 GMT) Full text and rfc822 format available.

Acknowledgement sent to Charles Plessy <plessy@debian.org>:
New Bug report received and forwarded. Copy sent to plessy@debian.org, Debian Policy List <debian-policy@lists.debian.org>. (Sat, 07 Jan 2012 06:15:05 GMT) Full text and rfc822 format available.

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

From: Charles Plessy <plessy@debian.org>
To: Debian Bug Tracking System <submit@bugs.debian.org>
Subject: debian-policy: Document VCS fields.
Date: Sat, 07 Jan 2012 15:10:47 +0900
[Message part 1 (text/plain, inline)]
Package: debian-policy
Version: 3.9.2.0
Severity: normal

Dear all,

now that thousands of pakcages use the VCS fields, I think that it is time to
document them in the Policy.  Please see the attached patch as a starting
point.

The Developers Reference already documents the VCS fields, and discusses
related points such as their use by the PTS.  I intentionally made the attached
patch very dry to avoid unnecessary overlaps.  If it is accepted, I will submit
a patch against the Def. Ref. to link to the Policy.

  http://www.debian.org/doc/manuals/developers-reference/best-pkging-practices#bpp-vcs

Have a nice day,

-- 
Charles
[0001-Document-VCS-fields-using-Developers-s-Reference-6.2.patch (text/html, attachment)]

Added tag(s) patch. Request was from Russ Allbery <rra@debian.org> to control@bugs.debian.org. (Sat, 07 Jan 2012 06:27:03 GMT) Full text and rfc822 format available.

Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#654958; Package debian-policy. (Sat, 07 Jan 2012 06:36:08 GMT) Full text and rfc822 format available.

Acknowledgement sent to Jonathan Nieder <jrnieder@gmail.com>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Sat, 07 Jan 2012 06:36:08 GMT) Full text and rfc822 format available.

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

From: Jonathan Nieder <jrnieder@gmail.com>
To: Charles Plessy <plessy@debian.org>
Cc: 654958@bugs.debian.org
Subject: Re: debian-policy: Document VCS fields.
Date: Sat, 7 Jan 2012 00:34:02 -0600
Hi Charles,

Charles Plessy wrote:

> +	      <tag>
> +		<tt>Vcs-arch</tt>, <tt>Vcs-bzr</tt> (Bazaar), <tt>Vcs-cvs</tt>,
> +		<tt>Vcs-darcs</tt>, <tt>Vcs-git</tt>, <tt>Vcs-hg</tt>
> +		(Mercurial), <tt>Vcs-mtn</tt> (Monotone), <tt>Vcs-svn</tt>
> +		(Subversion)
> +	      </tag>
> +	      <item>
> +		<p>
> +		  String identifying unequivocally the location of the
> +		  repository for anonymous access.  The field name identifies
> +		  the VCS.  More than one different VCS may be specified for the
> +		  same package.

If I keep my sources in svn, should I give a URL to the toplevel of the
repository (which is what one passes to "git svn clone -s" and allows
access to all branches) or one particular branch?  If a branch, which
branch, and should its content at the tip represent the last uploaded
version or is it allowed to be ahead of, behind, or even unrelated to
that?  Should the content at the tip match the uploaded package, or is
allowed to contain more, less, or some unrelated collection of files?

If I keep my sources using CVS, what is the format of the URL?  The
"cvs" package is an example.

What happens when the repository is moved or there is an outage?  Does
this represent a bug in the package like an email outage preventing
contact to the maintainer would?

Thanks and hope that helps,
Jonathan




Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#654958; Package debian-policy. (Sat, 07 Jan 2012 06:48:02 GMT) Full text and rfc822 format available.

Acknowledgement sent to Russ Allbery <rra@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Sat, 07 Jan 2012 06:48:03 GMT) Full text and rfc822 format available.

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

From: Russ Allbery <rra@debian.org>
To: 654958@bugs.debian.org, Charles Plessy <plessy@debian.org>
Subject: Re: Bug#654958: debian-policy: Document VCS fields.
Date: Fri, 06 Jan 2012 22:45:13 -0800
Jonathan Nieder <jrnieder@gmail.com> writes:

> If I keep my sources in svn, should I give a URL to the toplevel of the
> repository (which is what one passes to "git svn clone -s" and allows
> access to all branches) or one particular branch?

For debcheckout to work properly, you want to specify a branch.

> If a branch, which branch, and should its content at the tip represent
> the last uploaded version or is it allowed to be ahead of, behind, or
> even unrelated to that?  Should the content at the tip match the
> uploaded package, or is allowed to contain more, less, or some unrelated
> collection of files?

Also, for a Git repository, what do you do if the Debian packaging isn't
on the master branch?  For example, for packages for which I'm also
upstream, I do upstream development on the master branch and Debian
packaging on a separate debian branch.

I've always found the Vcs-* headers a bit underspecified, or at least
limited.  (I'm fairly sure the answer to my question is that debcheckout,
which is the only real consumer of the Vcs-* headers that I know of other
than statistical analysis of types of repositories, just can't handle that
case at all.)

-- 
Russ Allbery (rra@debian.org)               <http://www.eyrie.org/~eagle/>




Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#654958; Package debian-policy. (Sat, 07 Jan 2012 07:15:05 GMT) Full text and rfc822 format available.

Acknowledgement sent to Jonathan Nieder <jrnieder@gmail.com>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Sat, 07 Jan 2012 07:15:05 GMT) Full text and rfc822 format available.

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

From: Jonathan Nieder <jrnieder@gmail.com>
To: 654958@bugs.debian.org
Cc: 600745@bugs.debian.org
Subject: Re: debian-policy: Document VCS fields.
Date: Sat, 7 Jan 2012 01:11:32 -0600
Russ Allbery wrote:

> Also, for a Git repository, what do you do if the Debian packaging isn't
> on the master branch?  For example, for packages for which I'm also
> upstream, I do upstream development on the master branch and Debian
> packaging on a separate debian branch.

I wonder if something like

	Vcs-Git: git://git.eyrie.org/kerberos/webauth.git squeeze

could be made to work.




Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#654958; Package debian-policy. (Sat, 07 Jan 2012 16:51:05 GMT) Full text and rfc822 format available.

Acknowledgement sent to Russ Allbery <rra@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Sat, 07 Jan 2012 16:51:05 GMT) Full text and rfc822 format available.

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

From: Russ Allbery <rra@debian.org>
To: Jonathan Nieder <jrnieder@gmail.com>
Cc: 654958@bugs.debian.org, 600745@bugs.debian.org
Subject: Re: Bug#654958: debian-policy: Document VCS fields.
Date: Sat, 07 Jan 2012 08:46:47 -0800
Jonathan Nieder <jrnieder@gmail.com> writes:
> Russ Allbery wrote:

>> Also, for a Git repository, what do you do if the Debian packaging isn't
>> on the master branch?  For example, for packages for which I'm also
>> upstream, I do upstream development on the master branch and Debian
>> packaging on a separate debian branch.

> I wonder if something like

> 	Vcs-Git: git://git.eyrie.org/kerberos/webauth.git squeeze

> could be made to work.

My understanding was that the debcheckout developers were not enthused
about adding a syntax that Git upstream didn't support, but I think that's
the only solution that anyone's come up with so far.

On the other hand, it is kind of silly for them to be in such widespread
use without Policy saying anything about them.  Maybe we should just
document them as they are and be explicit about the limitations, saying
things like:

    The information in the Vcs-* header should be sufficient to locate the
    repository used for packaging and access it anonymously.  It may or
    may not be the branch used for packaging any specific version of the
    package, and the packaging is not necessarily on the default branch.
    Additional investigation is often required to find the part of the
    repository used for current development or for any particular version
    of the package.

If, over time, debcheckout and our package metadata starts making more
explicit guarantees, we can always tighten the language later, but the
above reflects the current state of the archive.

-- 
Russ Allbery (rra@debian.org)               <http://www.eyrie.org/~eagle/>




Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#654958; Package debian-policy. (Sat, 07 Jan 2012 19:42:14 GMT) Full text and rfc822 format available.

Acknowledgement sent to Russ Allbery <rra@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Sat, 07 Jan 2012 19:42:14 GMT) Full text and rfc822 format available.

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

From: Russ Allbery <rra@debian.org>
To: 654958@bugs.debian.org
Subject: Re: Bug#654958: debian-policy: Document VCS fields.
Date: Sat, 07 Jan 2012 11:41:19 -0800
"Bernhard R. Link" <brlink@debian.org> writes:

> Something that was only added to git after that discussion was already
> running for a while is git-clone's -b. Sadly

> Vcs-Git: git://git.eyrie.org/kerberos/webauth.git -b squeeze

> does not work as debcheckout is not word splitting the argument, but the
> error message at least cites a command one can just copy to the shell
> and it will work.

I wonder if the debcheckout developers would be willing to adopt this
syntax, since that seems like a nice solution.

-- 
Russ Allbery (rra@debian.org)               <http://www.eyrie.org/~eagle/>




Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#654958; Package debian-policy. (Sun, 08 Jan 2012 09:24:14 GMT) Full text and rfc822 format available.

Acknowledgement sent to Jonathan Nieder <jrnieder@gmail.com>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Sun, 08 Jan 2012 09:24:19 GMT) Full text and rfc822 format available.

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

From: Jonathan Nieder <jrnieder@gmail.com>
To: Russ Allbery <rra@debian.org>
Cc: 654958@bugs.debian.org
Subject: Re: debian-policy: Document VCS fields.
Date: Sun, 8 Jan 2012 03:26:12 -0600
Russ Allbery wrote:

>                                                 Maybe we should just
> document them as they are and be explicit about the limitations, saying
> things like:
>
>     The information in the Vcs-* header should be sufficient to locate the
>     repository used for packaging and access it anonymously.  It may or
>     may not be the branch used for packaging any specific version of the
>     package, and the packaging is not necessarily on the default branch.
>     Additional investigation is often required to find the part of the
>     repository used for current development or for any particular version
>     of the package.
>
> If, over time, debcheckout and our package metadata starts making more
> explicit guarantees, we can always tighten the language later, but the
> above reflects the current state of the archive.

That sounds sensible to me.

Thanks,
Jonathan




Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#654958; Package debian-policy. (Sun, 08 Jan 2012 11:51:18 GMT) Full text and rfc822 format available.

Acknowledgement sent to Steve Langasek <vorlon@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Sun, 08 Jan 2012 11:51:20 GMT) Full text and rfc822 format available.

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

From: Steve Langasek <vorlon@debian.org>
To: Russ Allbery <rra@debian.org>, 654958@bugs.debian.org
Cc: Jonathan Nieder <jrnieder@gmail.com>, 600745@bugs.debian.org
Subject: Re: Bug#654958: debian-policy: Document VCS fields.
Date: Sun, 8 Jan 2012 03:46:46 +0100
[Message part 1 (text/plain, inline)]
On Sat, Jan 07, 2012 at 08:46:47AM -0800, Russ Allbery wrote:
> > I wonder if something like

> > 	Vcs-Git: git://git.eyrie.org/kerberos/webauth.git squeeze

> > could be made to work.

> My understanding was that the debcheckout developers were not enthused
> about adding a syntax that Git upstream didn't support, but I think that's
> the only solution that anyone's come up with so far.

> On the other hand, it is kind of silly for them to be in such widespread
> use without Policy saying anything about them.  Maybe we should just
> document them as they are and be explicit about the limitations, saying
> things like:

>     The information in the Vcs-* header should be sufficient to locate the
>     repository used for packaging and access it anonymously.  It may or
>     may not be the branch used for packaging any specific version of the
>     package, and the packaging is not necessarily on the default branch.
>     Additional investigation is often required to find the part of the
>     repository used for current development or for any particular version
>     of the package.

> If, over time, debcheckout and our package metadata starts making more
> explicit guarantees, we can always tighten the language later, but the
> above reflects the current state of the archive.

I object to policy specifying any Vcs-* fields in a way that does not
uniquely identify a Debian packaging branch.  Running debcheckout for a
package only to then have to guess at random which of 20 branches is the one
containing the packaging I care about[1] is nonsense, and I don't think this
has any business being in policy in the absence of sensible semantics.  The
field should in all cases point to the right branch, not just the right
repository, and in the absence of an acceptable per-branch URI syntax, it
ought not be standardized at all.

Now, given that git seems to be the only widespread VCS with theis problem, I
wouldn't object to codifying Vcs- fields for the others in the meantime; but
some people might find it equally unpalatable to specify fields for
everything except git.

-- 
Steve Langasek                   Give me a lever long enough and a Free OS
Debian Developer                   to set it on, and I can move the world.
Ubuntu Developer                                    http://www.debian.org/
slangasek@ubuntu.com                                     vorlon@debian.org

[1] E.g., Vcs-Git: git://git.debian.org/~lamont/util-linux.git
[signature.asc (application/pgp-signature, inline)]

Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#654958; Package debian-policy. (Sun, 08 Jan 2012 12:57:03 GMT) Full text and rfc822 format available.

Acknowledgement sent to Charles Plessy <plessy@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Sun, 08 Jan 2012 12:57:12 GMT) Full text and rfc822 format available.

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

From: Charles Plessy <plessy@debian.org>
To: 654958@bugs.debian.org
Subject: Re: Bug#654958: debian-policy: Document VCS fields.
Date: Sun, 8 Jan 2012 21:55:48 +0900
[Message part 1 (text/plain, inline)]
Hi all,

this is a grouped answer for Jonathan, Russ and Steve.

From what I see in Sid, only 37 Subversion URLs contain the string ‘branch’.
This matches well with the practice I know in the Debian Med and Debian Science
teams, where we indicate the trunk.

For Git, as discussed in this thread, it is not possible to specify the branch
in the URL.  I hope that it will be possible one day; I miss the nice URLs of
Subversion, where the some commands can operate equally on local and remote
repositories.

I have proposed in http://bugs.debian.org/562254 to allow README.source to give
additional information related to VCSes.  This would also offer an optional
workaround for the packages managed in Git repositories which do not have a
usual layout. 

Vcs-Svn and Vcs-Git are by far the most frequent fields.  In my opinion, the
thousands of packages using them define a common practice, and for that reason
I think that it should be documented in the Policy.

We could provide examples or specific instructions for Svn, Git and the other
VCS types, like CVS.  But I am not sure it is necessary, as it may give the
wrong impression in terms of how the field is (not) precisely specified.  For
that reason, I like the wording proposed by Russ.

Lastly, like the Maintainer, Uploader or Homepage fields, the VCS fields can be
outdated.  I do not think that we can do much about it.

In the attached patch, I have rephrased the introduction paragraph to not
suggest that the access of the repository is “easy”, but I have not kept the
warning about “Additional investigation” from Russes wording (quoted below).
First, in the case of Subversion, the situation is clear apart from some corner
cases, for which I would not sure that all of them are intentional, and second,
for Git there are thousands of packages where the development occurs as
expected on the master branch.  I have also corrected the missing capital in
the field names, and removed the mention of “Vcs-*” as only the listed fields
are recognised by dpkg. 

Cheers,

-- Charles

Le Sat, Jan 07, 2012 at 08:46:47AM -0800, Russ Allbery a écrit :
> 
>     The information in the Vcs-* header should be sufficient to locate the
>     repository used for packaging and access it anonymously.  It may or
>     may not be the branch used for packaging any specific version of the
>     package, and the packaging is not necessarily on the default branch.
>     Additional investigation is often required to find the part of the
>     repository used for current development or for any particular version
>     of the package.
[0001-Document-VCS-fields-using-Developers-s-Reference-6.2.patch (text/x-diff, attachment)]

Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#654958; Package debian-policy. (Sun, 08 Jan 2012 13:51:12 GMT) Full text and rfc822 format available.

Acknowledgement sent to Steve Langasek <vorlon@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Sun, 08 Jan 2012 13:51:13 GMT) Full text and rfc822 format available.

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

From: Steve Langasek <vorlon@debian.org>
To: Charles Plessy <plessy@debian.org>, 654958@bugs.debian.org
Subject: Re: Bug#654958: debian-policy: Document VCS fields.
Date: Sun, 8 Jan 2012 14:50:14 +0100
[Message part 1 (text/plain, inline)]
On Sun, Jan 08, 2012 at 09:55:48PM +0900, Charles Plessy wrote:

> From what I see in Sid, only 37 Subversion URLs contain the string ‘branch’.
> This matches well with the practice I know in the Debian Med and Debian
> Science teams, where we indicate the trunk.

Yes.  By the nature of svn, the Vcs-Svn URI always unambiguously refers to a
single branch ("trunk" is a branch).  It's *only* the Vcs-Git usage is
broken.

> Vcs-Svn and Vcs-Git are by far the most frequent fields.  In my opinion,
> the thousands of packages using them define a common practice, and for
> that reason I think that it should be documented in the Policy.

Policy is for documenting what *SHOULD* be done.  It doesn't matter if it's
10 or 1000 packages that are using Vcs-Git today; if the syntax is broken,
it shouldn't go in policy.

-- 
Steve Langasek                   Give me a lever long enough and a Free OS
Debian Developer                   to set it on, and I can move the world.
Ubuntu Developer                                    http://www.debian.org/
slangasek@ubuntu.com                                     vorlon@debian.org
[signature.asc (application/pgp-signature, inline)]

Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#654958; Package debian-policy. (Sun, 08 Jan 2012 15:06:15 GMT) Full text and rfc822 format available.

Acknowledgement sent to "Bernhard R. Link" <brlink@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Sun, 08 Jan 2012 15:06:15 GMT) Full text and rfc822 format available.

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

From: "Bernhard R. Link" <brlink@debian.org>
To: Russ Allbery <rra@debian.org>
Cc: 654958@bugs.debian.org
Subject: Re: Bug#654958: debian-policy: Document VCS fields.
Date: Sun, 8 Jan 2012 15:31:07 +0100
* Russ Allbery <rra@debian.org> [120107 20:42]:
> "Bernhard R. Link" <brlink@debian.org> writes:
> > Something that was only added to git after that discussion was already
> > running for a while is git-clone's -b. Sadly
>
> > Vcs-Git: git://git.eyrie.org/kerberos/webauth.git -b squeeze
>
> > does not work as debcheckout is not word splitting the argument, but the
> > error message at least cites a command one can just copy to the shell
> > and it will work.
>
> I wonder if the debcheckout developers would be willing to adopt this
> syntax, since that seems like a nice solution.

I just submitted http://bugs.debian.org/655085 with a patch.
Hopfeully that either is accepted or gives some response what a
acceptable solution would need to look like...

        Bernhard R. Link




Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#654958; Package debian-policy. (Sun, 08 Jan 2012 17:39:10 GMT) Full text and rfc822 format available.

Acknowledgement sent to Jonathan Nieder <jrnieder@gmail.com>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Sun, 08 Jan 2012 17:39:10 GMT) Full text and rfc822 format available.

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

From: Jonathan Nieder <jrnieder@gmail.com>
To: 654958@bugs.debian.org
Subject: Re: debian-policy: Document VCS fields.
Date: Sun, 8 Jan 2012 11:42:00 -0600
Charles Plessy wrote:

> For Git, as discussed in this thread, it is not possible to specify the branch
> in the URL.  I hope that it will be possible one day

Git URLs deliberately represent a repository, not a branch.  That is
because branches and repositories for a package are simply different
notions in git (unlike in Subversion, where they are both described by
a path relative to the root of a repository shared by multiple
packages).  This is not specific to Git but is a feature shared by
CVS, for example.

To represent a branch in a remote repository, one generally uses a Git
URL, followed by a space, followed by the branch name.  This is the
syntax accepted by "git pull":

	git pull git://git.example.com/path/to/repo for-charles

And it is the syntax generated by pull requests with the "git request-pull"
command.

All that said, I'm happy with any delimiter for the Vcs-Git field, as
long as it is not too ugly and it works.  And regarding git, I am
happy to be proven wrong if someone has ideas that lead to a better
workflow without breaking existing users too much (file a bug report
when you find them.:)).

Hope that helps,
Jonathan




Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#654958; Package debian-policy. (Sun, 08 Jan 2012 17:54:05 GMT) Full text and rfc822 format available.

Acknowledgement sent to Russ Allbery <rra@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Sun, 08 Jan 2012 17:54:05 GMT) Full text and rfc822 format available.

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

From: Russ Allbery <rra@debian.org>
To: Steve Langasek <vorlon@debian.org>
Cc: 654958@bugs.debian.org, Jonathan Nieder <jrnieder@gmail.com>, 600745@bugs.debian.org
Subject: Re: Bug#654958: debian-policy: Document VCS fields.
Date: Sun, 08 Jan 2012 09:50:32 -0800
Steve Langasek <vorlon@debian.org> writes:

> I object to policy specifying any Vcs-* fields in a way that does not
> uniquely identify a Debian packaging branch.  Running debcheckout for a
> package only to then have to guess at random which of 20 branches is the
> one containing the packaging I care about[1] is nonsense, and I don't
> think this has any business being in policy in the absence of sensible
> semantics.  The field should in all cases point to the right branch, not
> just the right repository, and in the absence of an acceptable
> per-branch URI syntax, it ought not be standardized at all.

While I'm sympathetic to this position, the concern that I have with going
this route is that "what branch I care about" is never going to be a
clearly-defined concept.  Is it the branch for unstable?  The latest
packaging, which may only be in experimental, or may not have been
uploaded at all?  Are you working on a stable update, in which case you
need another branch entirely?

This comes back to the basic problem that while putting this metadata in
the package is certainly convenient and made the metadata available
quickly, it has some inherent limitations since the VCS information is not
a property of the package itself.  Rather, it's a property of how the
package is being maintained, which can change without changing the
package.

Given the fundamental issue that there are multiple things you may want
(the latest stuff, the last uploaded stuff, the unstable stuff, even the
stable stuff), I don't see how we'll ever, for any VCS (not just Git), get
any better than "here's the repository and you may have to do additional
work to figure out the right branch" in the VCS-* headers.  As Charles
points out, you need an explanation for humans, not computers, in some
other location, such as README.source.

What we *can* do is identify the repository, so I think we should
seriously consider standardizing that and leave the explanation of the
branches to README.source.

> Now, given that git seems to be the only widespread VCS with theis
> problem, I wouldn't object to codifying Vcs- fields for the others in
> the meantime; but some people might find it equally unpalatable to
> specify fields for everything except git.

CVS has the same issue, not that it's widely used any more.  But even
Subversion has the broader problem that it's not at all clear which branch
to designate.

-- 
Russ Allbery (rra@debian.org)               <http://www.eyrie.org/~eagle/>




Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#654958; Package debian-policy. (Sun, 08 Jan 2012 23:15:03 GMT) Full text and rfc822 format available.

Acknowledgement sent to Jonathan Nieder <jrnieder@gmail.com>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Sun, 08 Jan 2012 23:15:03 GMT) Full text and rfc822 format available.

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

From: Jonathan Nieder <jrnieder@gmail.com>
To: 654958@bugs.debian.org
Subject: Re: debian-policy: Document VCS fields.
Date: Sun, 8 Jan 2012 17:18:26 -0600
Steve Langasek wrote:

> Yes.  By the nature of svn, the Vcs-Svn URI always unambiguously refers to a
> single branch ("trunk" is a branch).

FWIW, I would be happy to see at least that documented.  (It would
provide a reason to propose this change in the eglibc package. :))




Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#654958; Package debian-policy. (Mon, 09 Jan 2012 03:09:08 GMT) Full text and rfc822 format available.

Acknowledgement sent to James McCoy <vega.james@gmail.com>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Mon, 09 Jan 2012 03:09:08 GMT) Full text and rfc822 format available.

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

From: James McCoy <vega.james@gmail.com>
To: Russ Allbery <rra@debian.org>, 600745@bugs.debian.org
Cc: Steve Langasek <vorlon@debian.org>, 654958@bugs.debian.org, Jonathan Nieder <jrnieder@gmail.com>
Subject: Re: Bug#600745: Bug#654958: debian-policy: Document VCS fields.
Date: Sun, 8 Jan 2012 22:06:08 -0500
[Message part 1 (text/plain, inline)]
On Sun, Jan 08, 2012 at 09:50:32AM -0800, Russ Allbery wrote:
> Steve Langasek <vorlon@debian.org> writes:
> 
> > I object to policy specifying any Vcs-* fields in a way that does not
> > uniquely identify a Debian packaging branch.  Running debcheckout for a
> > package only to then have to guess at random which of 20 branches is the
> > one containing the packaging I care about[1] is nonsense, and I don't
> > think this has any business being in policy in the absence of sensible
> > semantics.  The field should in all cases point to the right branch, not
> > just the right repository, and in the absence of an acceptable
> > per-branch URI syntax, it ought not be standardized at all.
> 
> While I'm sympathetic to this position, the concern that I have with going
> this route is that "what branch I care about" is never going to be a
> clearly-defined concept.  Is it the branch for unstable?  The latest
> packaging, which may only be in experimental, or may not have been
> uploaded at all?  Are you working on a stable update, in which case you
> need another branch entirely?

I have to agree with Russ here.  It's easy enough to change the Vcs-*
fields so they're appropriate for uploads to unstable or experimental,
but as soon as a package transitions out of unstable the field is
potentially out of date.

If there's a non-trivial branching policy, then that could be described
in README.source (or a new README.vcs since it's not directly related to
working with the source package).

This is more relevant for non-DVCS (like svn) since checking out an
entire project's repository instead of just the development branch can
take much more time and space.  The problem is that the exact VCS where
it is most beneficial to provide the most specific information are also
the ones where not having the correct information (e.g., still having
the URL for unstable when the package is in stable) makes the checkout
useless.

> > Now, given that git seems to be the only widespread VCS with theis
> > problem, I wouldn't object to codifying Vcs- fields for the others in
> > the meantime; but some people might find it equally unpalatable to
> > specify fields for everything except git.

Any VCS workflow which uses different branches for different releases
(or uploads to places other than unstable) is going to have this
problem.

-- 
James
GPG Key: 4096R/331BA3DB 2011-12-05 James McCoy <jamessan@debian.org>
[signature.asc (application/pgp-signature, inline)]

Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#654958; Package debian-policy. (Wed, 09 May 2012 18:30:03 GMT) Full text and rfc822 format available.

Acknowledgement sent to "Bernhard R. Link" <brlink@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Wed, 09 May 2012 18:30:03 GMT) Full text and rfc822 format available.

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

From: "Bernhard R. Link" <brlink@debian.org>
To: 654958@bugs.debian.org
Subject: Re: Bug#654958: debian-policy: Document VCS fields.
Date: Wed, 9 May 2012 20:32:26 +0200
* Bernhard R. Link <brlink@debian.org> [120108 14:03]:
> * Russ Allbery <rra@debian.org> [120107 20:42]:
> > "Bernhard R. Link" <brlink@debian.org> writes:
> > > Something that was only added to git after that discussion was already
> > > running for a while is git-clone's -b. Sadly
> >
> > > Vcs-Git: git://git.eyrie.org/kerberos/webauth.git -b squeeze
> >
> > > does not work as debcheckout is not word splitting the argument, but the
> > > error message at least cites a command one can just copy to the shell
> > > and it will work.
> >
> > I wonder if the debcheckout developers would be willing to adopt this
> > syntax, since that seems like a nice solution.
>
> I just submitted http://bugs.debian.org/655085 with a patch.

The patch was applied to debcheckout, so Vcs-Git: can now specify
a branch to use.

	Bernhard R. Link




Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#654958; Package debian-policy. (Thu, 28 Jun 2012 00:12:03 GMT) Full text and rfc822 format available.

Acknowledgement sent to Charles Plessy <plessy@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Thu, 28 Jun 2012 00:12:03 GMT) Full text and rfc822 format available.

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

From: Charles Plessy <plessy@debian.org>
To: "Bernhard R. Link" <brlink@debian.org>, 654958@bugs.debian.org
Subject: Re: Bug#654958: debian-policy: Document VCS fields.
Date: Thu, 28 Jun 2012 09:10:31 +0900
[Message part 1 (text/plain, inline)]
Le Wed, May 09, 2012 at 08:32:26PM +0200, Bernhard R. Link a écrit :
> * Bernhard R. Link <brlink@debian.org> [120108 14:03]:
> > * Russ Allbery <rra@debian.org> [120107 20:42]:
> > > "Bernhard R. Link" <brlink@debian.org> writes:
> > > > Something that was only added to git after that discussion was already
> > > > running for a while is git-clone's -b. Sadly
> > >
> > > > Vcs-Git: git://git.eyrie.org/kerberos/webauth.git -b squeeze
> > >
> > > > does not work as debcheckout is not word splitting the argument, but the
> > > > error message at least cites a command one can just copy to the shell
> > > > and it will work.
> > >
> > > I wonder if the debcheckout developers would be willing to adopt this
> > > syntax, since that seems like a nice solution.
> >
> > I just submitted http://bugs.debian.org/655085 with a patch.
> 
> The patch was applied to debcheckout, so Vcs-Git: can now specify
> a branch to use.

Thanks a lot !

Would the following patch be acceptable now ?

Have a nice day,

-- 
Charles Plessy
Tsurumi, Kanagawa, Japan
[0001-Document-VCS-fields-using-Developers-s-Reference-6.2.patch (text/x-diff, attachment)]

Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#654958; Package debian-policy. (Thu, 28 Jun 2012 00:27:03 GMT) Full text and rfc822 format available.

Acknowledgement sent to Jonathan Nieder <jrnieder@gmail.com>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Thu, 28 Jun 2012 00:27:03 GMT) Full text and rfc822 format available.

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

From: Jonathan Nieder <jrnieder@gmail.com>
To: Charles Plessy <plessy@debian.org>
Cc: 654958@bugs.debian.org, "Bernhard R. Link" <brlink@debian.org>
Subject: Re: debian-policy: Document VCS fields.
Date: Wed, 27 Jun 2012 19:25:10 -0500
Hi Charles,

Charles Plessy wrote:

> Would the following patch be acceptable now ?

Getting a lot closer.  Some questions:

[...]
> +++ b/policy.sgml
[...]
> @@ -3737,6 +3739,42 @@ Checksums-Sha256:
>  	    details.
>  	  </p>
>  	</sect1>
> +
> +	<sect1 id="f-VCS-fields">
> +	  <heading>Version Control System (VCS) fields</heading>
> +
> +	  <p>
> +	    Debian source packages are increasingly developed using VCSs.  The
> +	    purpose of the following fields is to indicate to the users where
> +	    they can access to the package's repository.

Maybe something like "... to indicate a publically accessible
repository where one can find packaging work in progress".

[...]
> +	      <tag><tt>Vcs-Browser</tt></tag>
> +	      <item>
> +		<p>
> +		  HTTP URL of a web-browsable repository.

A common mistake is to put an HTTP URL for a raw git repository
instead of gitweb in this field.  If possible, I would like the
wording to warn people not to do that.  How about

		  HTTP URL of a web interface for browsing the repository.

?

[...]
> +		  The field name identifies the VCS. The field's value should
> +		  be sufficient to locate the repository and access it
> +		  anonymously on the main branch used for packaging.  In the
> +		  case of Git, this is indicated with a <tt>-b</tt> argument,
> +		  like with the <tt>git clone</tt> command.  More than one
> +		  different VCS may be specified for the same package.

Suppose my repository has "stable", "testing", "sid", and
"experimental" branches used to prepare uploads for s-p-u, t-p-u,
unstable, and experimental, respectively.  Which is the main branch
used for packaging?

This is not meant as a hypothetical question.  eglibc and the linux
kernel are both actively developed in many branches at once.  If
there's no good obvious answer, some wording like "on a branch used
for packaging" sounds fine to me.

One other worry: I understand that you do not want to define the
syntax used for each version control system, but the wording "should
be sufficient to locate the repository" seems a little _too_ fuzzy.
Would something like "uses the version control system's conventional
syntax for describing repository locations and should be sufficient to
locate ..." work?  I want to make sure it is clear that a gitweb or
wsvn URL is not appropriate here.

Except as noted above, looks good to me.

Hope that helps,
Jonathan




Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#654958; Package debian-policy. (Mon, 09 Jul 2012 01:21:08 GMT) Full text and rfc822 format available.

Acknowledgement sent to Jonathan Nieder <jrnieder@gmail.com>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Mon, 09 Jul 2012 01:21:08 GMT) Full text and rfc822 format available.

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

From: Jonathan Nieder <jrnieder@gmail.com>
To: Charles Plessy <plessy@debian.org>
Cc: 654958@bugs.debian.org, "Bernhard R. Link" <brlink@debian.org>
Subject: Re: debian-policy: Document VCS fields.
Date: Sun, 8 Jul 2012 20:19:12 -0500
[Message part 1 (text/plain, inline)]
Charles Plessy wrote:

> Would the following patch be acceptable now ?

My feedback got no replies, so I can only assume that everyone was so
awestruck by the suggestions that they were lost for words.

Here's an updated patch.  Improvements welcome.

Looking forward to your thoughts,
Jonathan
[Document-VCS-fields-using-Developers-s-Reference-6.2.patch (text/plain, attachment)]

Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#654958; Package debian-policy. (Mon, 09 Jul 2012 08:54:15 GMT) Full text and rfc822 format available.

Acknowledgement sent to Charles Plessy <plessy@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Mon, 09 Jul 2012 08:54:15 GMT) Full text and rfc822 format available.

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

From: Charles Plessy <plessy@debian.org>
To: 654958@bugs.debian.org
Subject: Re: Bug#654958: debian-policy: Document VCS fields.
Date: Mon, 9 Jul 2012 17:52:55 +0900
Le Sun, Jul 08, 2012 at 08:19:12PM -0500, Jonathan Nieder a écrit :
> 
> My feedback got no replies, so I can only assume that everyone was so
> awestruck by the suggestions that they were lost for words.

... or assume holidays :)

Thanks a lot for the revised patch.  From my point of view, it is consensual
and ready for being applied, so I second it.

Have a nice day,

-- 
Charles
Tsurumi, Kanagawa, Japan




Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#654958; Package debian-policy. (Fri, 13 Jul 2012 02:51:53 GMT) Full text and rfc822 format available.

Acknowledgement sent to Russ Allbery <rra@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Fri, 13 Jul 2012 02:52:12 GMT) Full text and rfc822 format available.

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

From: Russ Allbery <rra@debian.org>
To: Jonathan Nieder <jrnieder@gmail.com>
Cc: 654958@bugs.debian.org, Charles Plessy <plessy@debian.org>, "Bernhard R. Link" <brlink@debian.org>
Subject: Re: Bug#654958: debian-policy: Document VCS fields.
Date: Thu, 12 Jul 2012 19:45:17 -0700
Jonathan Nieder <jrnieder@gmail.com> writes:

> diff --git a/policy.sgml b/policy.sgml
> index 52dbb26a..371123e1 100644
> --- a/policy.sgml
> +++ b/policy.sgml
> @@ -2631,6 +2631,7 @@ Package: libc6
>  	    <item><qref id="sourcebinarydeps"><tt>Build-Depends</tt> et al</qref></item>
>  	    <item><qref id="f-Standards-Version"><tt>Standards-Version</tt></qref> (recommended)</item>
>  	    <item><qref id="f-Homepage"><tt>Homepage</tt></qref></item>
> +	    <item><qref id="f-VCS-fields"><tt>VCS fields</tt></qref></item>

This is the only field in this index that doesn't list an actual field
name.  Minor, but for consistency should we instead say
"<tt>Vcs-Browser</tt>, <tt>Vcs-Git</tt>, et al."?  (Git because it's the
most commonly-used one, IIRC.)

>  	  </list>
>  	</p>
>  
> @@ -2728,6 +2729,7 @@ Package: libc6
>  	  <item><qref id="f-Checksums"><tt>Checksums-Sha1</tt>
>  	      and <tt>Checksums-Sha256</tt></qref> (recommended)</item>
>  	  <item><qref id="f-Files"><tt>Files</tt></qref> (mandatory)</item>
> +	  <item><qref id="f-VCS-fields"><tt>VCS fields</tt></qref></item>

Likewise here.  (Here, we've always listed every single field in the past,
but I've always thought that section heading for the Build-Depends family
was ugly and would like to change it to use et al. here as well.)

> +	<sect1 id="f-VCS-fields">
> +	  <heading>Version Control System (VCS) fields</heading>
> +
> +	  <p>
> +	    Debian source packages are increasingly developed using VCSs.  The
> +	    purpose of the following fields is to indicate a publicly accessible
> +	    repository where the package is developed.

"Package" is ambiguous.  I think we need to make it crystal-clear that
this is for the Debian packaging, not for upstream's repository.  That's
the main thing that people get confused by.

How about "where the Debian source package is developed"?

> +	    <taglist>
> +	      <tag><tt>Vcs-Browser</tt></tag>
> +	      <item>
> +		<p>
> +		  HTTP URL of a web interface for browsing the repository.

*Very* minor nit: Some people now only provide HTTPS, not HTTP, on their
web hosts on the grounds that everything one does on-line should be
encrypted by default.  I don't think the "HTTP" here is adding anything; I
would just say "URL of a web interface for browsing the repository."

> +	      <tag>
> +		<tt>Vcs-Arch</tt>, <tt>Vcs-Bzr</tt> (Bazaar), <tt>Vcs-Cvs</tt>,
> +		<tt>Vcs-Darcs</tt>, <tt>Vcs-Git</tt>, <tt>Vcs-Hg</tt>
> +		(Mercurial), <tt>Vcs-Mtn</tt> (Monotone), <tt>Vcs-Svn</tt>
> +		(Subversion)
> +	      </tag>
> +	      <item>
> +		<p>
> +		  The field name identifies the VCS. The field's value uses the
> +		  version control system's conventional syntax for describing
> +		  repository locations and should be sufficient to locate the
> +		  repository and access it anonymously on a branch used for
> +		  packaging.
> +		</p>

"...on the default branch used for packaging new releases" perhaps?  It's
hard to figure out what to say here about repositories where each Debian
release is on a new branch.  I'm not sure how to deal with that, although
we probably have to bail on the problem at least somewhat.

Maybe we should instead say something like:

    ...and should be sufficient to locate the repository used for
    packaging.  Ideally, it also locates the branch used for development
    of new Debian packages.

> +		<p>
> +		  In the case of Git, the value consists of a Git URL

"...of a URL".  Otherwise, it sounds like the only acceptable value are
specifically git:// URLs.  Comma after URL.

> +		  optionally followed by the word <tt>-b</tt> and the name of
> +		  a branch in the indicated repository, like with the
> +		  <tt>git clone</tt> command.  If no branch is specified, the
> +		  packaging should be on the default branch.

s/like with/following the syntax of/

Otherwise looks good to me.

-- 
Russ Allbery (rra@debian.org)               <http://www.eyrie.org/~eagle/>




Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#654958; Package debian-policy. (Fri, 13 Jul 2012 04:02:38 GMT) Full text and rfc822 format available.

Acknowledgement sent to Jonathan Nieder <jrnieder@gmail.com>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Fri, 13 Jul 2012 04:03:21 GMT) Full text and rfc822 format available.

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

From: Jonathan Nieder <jrnieder@gmail.com>
To: Russ Allbery <rra@debian.org>
Cc: 654958@bugs.debian.org, Charles Plessy <plessy@debian.org>, "Bernhard R. Link" <brlink@debian.org>
Subject: Re: debian-policy: Document VCS fields.
Date: Thu, 12 Jul 2012 22:51:12 -0500
[Message part 1 (text/plain, inline)]
Russ Allbery wrote:

> Maybe we should instead say something like:
>
>     ...and should be sufficient to locate the repository used for
>     packaging.  Ideally, it also locates the branch used for development
>     of new Debian packages.

With s/new Debian packages/new versions of the Debian package/, makes
sense.

>> +		<p>
>> +		  In the case of Git, the value consists of a Git URL
>
> "...of a URL".  Otherwise, it sounds like the only acceptable value are
> specifically git:// URLs.  Comma after URL.

Yes, ok.  I was poisoned by the git-clone(1) manpage. :)  It describes
accepted repository address formats in a section headed "GIT URLS".

[... other nice suggestions snipped ...]
> Otherwise looks good to me.

Thanks again for your help.  I've applied all suggested changes.
Interdiff and updated patch attached.

Jonathan
[interdiff (text/plain, attachment)]
[Document-VCS-fields-using-Developers-s-Reference-6.2.patch (text/plain, attachment)]

Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#654958; Package debian-policy. (Fri, 13 Jul 2012 04:20:09 GMT) Full text and rfc822 format available.

Acknowledgement sent to Russ Allbery <rra@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Fri, 13 Jul 2012 04:20:34 GMT) Full text and rfc822 format available.

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

From: Russ Allbery <rra@debian.org>
To: Jonathan Nieder <jrnieder@gmail.com>
Cc: 654958@bugs.debian.org, Charles Plessy <plessy@debian.org>, "Bernhard R. Link" <brlink@debian.org>
Subject: Re: debian-policy: Document VCS fields.
Date: Thu, 12 Jul 2012 21:04:57 -0700
Jonathan Nieder <jrnieder@gmail.com> writes:

> Thanks again for your help.  I've applied all suggested changes.
> Interdiff and updated patch attached.

Looks good to me -- seconded.

-- 
Russ Allbery (rra@debian.org)               <http://www.eyrie.org/~eagle/>




Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#654958; Package debian-policy. (Sat, 14 Jul 2012 01:30:06 GMT) Full text and rfc822 format available.

Acknowledgement sent to Charles Plessy <plessy@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Sat, 14 Jul 2012 01:30:06 GMT) Full text and rfc822 format available.

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

From: Charles Plessy <plessy@debian.org>
To: 654958@bugs.debian.org
Subject: Re: Bug#654958: debian-policy: Document VCS fields.
Date: Sat, 14 Jul 2012 10:19:46 +0900
Le Thu, Jul 12, 2012 at 09:04:57PM -0700, Russ Allbery a écrit :
> Jonathan Nieder <jrnieder@gmail.com> writes:
> 
> > Thanks again for your help.  I've applied all suggested changes.
> > Interdiff and updated patch attached.
> 
> Looks good to me -- seconded.

Hello everybody,

Formally speaking, we need one more person to second that change, since
Jonathan is not yet a DD (I hope this will happen soon !).

Have a nice week-end, 

-- 
Charles Plessy
Tsurumi, Kanagawa, Japan




Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#654958; Package debian-policy. (Sat, 14 Jul 2012 09:09:06 GMT) 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 Policy List <debian-policy@lists.debian.org>. (Sat, 14 Jul 2012 09:09:06 GMT) Full text and rfc822 format available.

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

From: Guillem Jover <guillem@debian.org>
To: Jonathan Nieder <jrnieder@gmail.com>, 654958@bugs.debian.org
Cc: Russ Allbery <rra@debian.org>, Charles Plessy <plessy@debian.org>, "Bernhard R. Link" <brlink@debian.org>
Subject: Re: Bug#654958: debian-policy: Document VCS fields.
Date: Sat, 14 Jul 2012 10:51:07 +0200
[Message part 1 (text/plain, inline)]
Hi!

On Thu, 2012-07-12 at 22:51:12 -0500, Jonathan Nieder wrote:
> Thanks again for your help.  I've applied all suggested changes.
> Interdiff and updated patch attached.

Seconded.

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

Removed tag(s) patch. Request was from Charles Plessy <plessy@debian.org> to control@bugs.debian.org. (Sat, 14 Jul 2012 09:30:07 GMT) Full text and rfc822 format available.

Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#654958; Package debian-policy. (Mon, 16 Jul 2012 05:54:05 GMT) Full text and rfc822 format available.

Acknowledgement sent to "Bernhard R. Link" <brlink@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Mon, 16 Jul 2012 05:54:05 GMT) Full text and rfc822 format available.

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

From: "Bernhard R. Link" <brlink@debian.org>
To: 654958@bugs.debian.org
Subject: Re: debian-policy: Document VCS fields.
Date: Mon, 16 Jul 2012 07:16:52 +0200
> +	      <tag>
> +		<tt>Vcs-Arch</tt>, <tt>Vcs-Bzr</tt> (Bazaar), <tt>Vcs-Cvs</tt>,
> +		<tt>Vcs-Darcs</tt>, <tt>Vcs-Git</tt>, <tt>Vcs-Hg</tt>
> +		(Mercurial), <tt>Vcs-Mtn</tt> (Monotone), <tt>Vcs-Svn</tt>
> +		(Subversion)
> +	      </tag>
> +	      <item>
> +		<p>
> +		  The field name identifies the VCS. The field's value uses the
> +		  version control system's conventional syntax for describing
> +		  repository locations and should be sufficient to locate the
> +		  repository used for packaging. Ideally, it also locates the
> +		  branch used for development of new versions of the Debian
> +		  package.
> +		</p>
> +		<p>
> +		  In the case of Git, the value consists of a URL, optionally
> +		  followed by the word <tt>-b</tt> and the name of a branch in
> +		  the indicated repository, following the syntax of the
> +		  <tt>git clone</tt> command.  If no branch is specified, the
> +		  packaging should be on the default branch.
> +		</p>

Why only document git and not the syntax of the other fields?

cvs: a identifier suiteable for cvs -d (i.e. usually starting with :pserver:),
followed by an optional module name (seperated by a space).

I think it might also make sense to explicitly request that the fields should
describe an anonymous checkout.

        Bernhard R. Link



Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#654958; Package debian-policy. (Mon, 16 Jul 2012 06:15:03 GMT) Full text and rfc822 format available.

Acknowledgement sent to Jonathan Nieder <jrnieder@gmail.com>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Mon, 16 Jul 2012 06:15:03 GMT) Full text and rfc822 format available.

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

From: Jonathan Nieder <jrnieder@gmail.com>
To: "Bernhard R. Link" <brlink@debian.org>
Cc: 654958@bugs.debian.org
Subject: Re: debian-policy: Document VCS fields.
Date: Mon, 16 Jul 2012 01:12:24 -0500
Hi Bernhard,

Bernhard R. Link wrote:

>> +		  In the case of Git, the value consists of a URL, optionally
>> +		  followed by the word <tt>-b</tt> and the name of a branch in
>> +		  the indicated repository, following the syntax of the
>> +		  <tt>git clone</tt> command.  If no branch is specified, the
>> +		  packaging should be on the default branch.
>> +		</p>
>
> Why only document git and not the syntax of the other fields?

Thanks.

My excuse is that a syntax allowing Vcs-Git to refer to a particular
branch was considered a blocker for documenting the Vcs-* fields at
all.

Would you be broken-hearted if I asked you to file a new bug for the
other VCSs that also have weird syntaxes worth documenting?

[...]
> I think it might also make sense to explicitly request that the fields should
> describe an anonymous checkout.

Yeah, good catch --- the current text that tries to do that is
only the rationale, and it's better to say it somewhere normative.

How about this?

diff --git i/policy.sgml w/policy.sgml
index 7d514921..58bde0bb 100644
--- i/policy.sgml
+++ w/policy.sgml
@@ -3766,8 +3766,9 @@ Checksums-Sha256:
 		<p>
 		  The field name identifies the VCS. The field's value uses the
 		  version control system's conventional syntax for describing
-		  repository locations and should be sufficient to locate the
-		  repository used for packaging. Ideally, it also locates the
+		  repository locations and should be sufficient to locate a
+		  publicly accessible repository used for packaging.
+		  Ideally, it also locates the
 		  branch used for development of new versions of the Debian
 		  package.
 		</p>



Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#654958; Package debian-policy. (Mon, 16 Jul 2012 18:00:06 GMT) Full text and rfc822 format available.

Acknowledgement sent to Russ Allbery <rra@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Mon, 16 Jul 2012 18:00:06 GMT) Full text and rfc822 format available.

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

From: Russ Allbery <rra@debian.org>
To: Jonathan Nieder <jrnieder@gmail.com>
Cc: 654958@bugs.debian.org, "Bernhard R. Link" <brlink@debian.org>
Subject: Re: Bug#654958: debian-policy: Document VCS fields.
Date: Mon, 16 Jul 2012 10:47:48 -0700
Jonathan Nieder <jrnieder@gmail.com> writes:

> How about this?

> diff --git i/policy.sgml w/policy.sgml
> index 7d514921..58bde0bb 100644
> --- i/policy.sgml
> +++ w/policy.sgml
> @@ -3766,8 +3766,9 @@ Checksums-Sha256:
>  		<p>
>  		  The field name identifies the VCS. The field's value uses the
>  		  version control system's conventional syntax for describing
> -		  repository locations and should be sufficient to locate the
> -		  repository used for packaging. Ideally, it also locates the
> +		  repository locations and should be sufficient to locate a
> +		  publicly accessible repository used for packaging.
> +		  Ideally, it also locates the
>  		  branch used for development of new versions of the Debian
>  		  package.
>  		</p>

Looks good to me.  (Tiny grammar nit: "publicly-accessible", but I can fix
that when committing.)

-- 
Russ Allbery (rra@debian.org)               <http://www.eyrie.org/~eagle/>



Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#654958; Package debian-policy. (Mon, 16 Jul 2012 18:18:03 GMT) Full text and rfc822 format available.

Acknowledgement sent to Russ Allbery <rra@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Mon, 16 Jul 2012 18:18:03 GMT) Full text and rfc822 format available.

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

From: Russ Allbery <rra@debian.org>
To: blp@cs.stanford.edu
Cc: 654958@bugs.debian.org, Jonathan Nieder <jrnieder@gmail.com>, "Bernhard R. Link" <brlink@debian.org>
Subject: Re: Bug#654958: debian-policy: Document VCS fields.
Date: Mon, 16 Jul 2012 11:15:54 -0700
Ben Pfaff <blp@cs.stanford.edu> writes:

> Is a hyphen desirable there?
> http://en.wikipedia.org/wiki/Hyphen#Compound_modifiers says:

>     In the 19th century, it was common to hyphenate
>     adverb–adjective modifiers with the adverb ending in -ly.
>     However, this has become rare.  For example, wholly owned
>     subsidiary and quickly moving vehicle are unambiguous,
>     because the adverbs clearly modify the adjectives: "quickly"
>     cannot modify "vehicle".  However, if an adverb can also
>     function as an adjective, then a hyphen may be or should be
>     used for clarity, depending on the style guide.[3] For
>     example, the phrase more-important reasons ("reasons that are
>     more important") is distinguished from more important reasons
>     ("additional important reasons"), where more is an adjective.
>     Similarly, more-beautiful scenery (with a mass-noun) is
>     distinct from more beautiful scenery.  (In contrast, the
>     hyphen in "a more-important reason/a more important reason"
>     is not necessary.)  The hyphen in little-celebrated paintings
>     clarifies that one is not speaking of little paintings.

> By that logic, I would think that no hyphen is needed, because
> "publicly" cannot modify "repository".

Oh, good call.  You're right; Jonathan's original is better.  I didn't
think through the adverb vs. adjective distinction.  There's no ambiguity
without the hyphen since publicly is an adverb.

-- 
Russ Allbery (rra@debian.org)               <http://www.eyrie.org/~eagle/>



Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#654958; Package debian-policy. (Mon, 16 Jul 2012 18:45:03 GMT) Full text and rfc822 format available.

Acknowledgement sent to blp@cs.stanford.edu:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Mon, 16 Jul 2012 18:45:03 GMT) Full text and rfc822 format available.

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

From: Ben Pfaff <blp@cs.stanford.edu>
To: Russ Allbery <rra@debian.org>
Cc: 654958@bugs.debian.org, Jonathan Nieder <jrnieder@gmail.com>, "Bernhard R. Link" <brlink@debian.org>
Subject: Re: Bug#654958: debian-policy: Document VCS fields.
Date: Mon, 16 Jul 2012 11:13:55 -0700
Russ Allbery <rra@debian.org> writes:

> Jonathan Nieder <jrnieder@gmail.com> writes:
>
>> How about this?
>
>> diff --git i/policy.sgml w/policy.sgml
>> index 7d514921..58bde0bb 100644
>> --- i/policy.sgml
>> +++ w/policy.sgml
>> @@ -3766,8 +3766,9 @@ Checksums-Sha256:
>>  		<p>
>>  		  The field name identifies the VCS. The field's value uses the
>>  		  version control system's conventional syntax for describing
>> -		  repository locations and should be sufficient to locate the
>> -		  repository used for packaging. Ideally, it also locates the
>> +		  repository locations and should be sufficient to locate a
>> +		  publicly accessible repository used for packaging.
>> +		  Ideally, it also locates the
>>  		  branch used for development of new versions of the Debian
>>  		  package.
>>  		</p>
>
> Looks good to me.  (Tiny grammar nit: "publicly-accessible", but I can fix
> that when committing.)

Is a hyphen desirable there?
http://en.wikipedia.org/wiki/Hyphen#Compound_modifiers says:

    In the 19th century, it was common to hyphenate
    adverb–adjective modifiers with the adverb ending in -ly.
    However, this has become rare.  For example, wholly owned
    subsidiary and quickly moving vehicle are unambiguous,
    because the adverbs clearly modify the adjectives: "quickly"
    cannot modify "vehicle".  However, if an adverb can also
    function as an adjective, then a hyphen may be or should be
    used for clarity, depending on the style guide.[3] For
    example, the phrase more-important reasons ("reasons that are
    more important") is distinguished from more important reasons
    ("additional important reasons"), where more is an adjective.
    Similarly, more-beautiful scenery (with a mass-noun) is
    distinct from more beautiful scenery.  (In contrast, the
    hyphen in "a more-important reason/a more important reason"
    is not necessary.)  The hyphen in little-celebrated paintings
    clarifies that one is not speaking of little paintings.

By that logic, I would think that no hyphen is needed, because
"publicly" cannot modify "repository".

(I am no expert on English.)



Added indication that bug 654958 blocks 682282 Request was from Jonathan Nieder <jrnieder@gmail.com> to submit@bugs.debian.org. (Fri, 20 Jul 2012 23:00:04 GMT) Full text and rfc822 format available.

Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#654958; Package debian-policy. (Sun, 12 Aug 2012 19:48:06 GMT) Full text and rfc822 format available.

Acknowledgement sent to Russ Allbery <rra@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Sun, 12 Aug 2012 19:48:06 GMT) Full text and rfc822 format available.

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

From: Russ Allbery <rra@debian.org>
To: Jonathan Nieder <jrnieder@gmail.com>
Cc: 654958@bugs.debian.org, Charles Plessy <plessy@debian.org>, "Bernhard R. Link" <brlink@debian.org>
Subject: Re: Bug#654958: debian-policy: Document VCS fields.
Date: Sun, 12 Aug 2012 12:45:50 -0700
Jonathan Nieder <jrnieder@gmail.com> writes:

> Thanks again for your help.  I've applied all suggested changes.
> Interdiff and updated patch attached.

Thanks, this has been applied for the next release.

-- 
Russ Allbery (rra@debian.org)               <http://www.eyrie.org/~eagle/>



Added tag(s) pending. Request was from Russ Allbery <rra@debian.org> to control@bugs.debian.org. (Sun, 12 Aug 2012 19:48:08 GMT) Full text and rfc822 format available.

Reply sent to Russ Allbery <rra@debian.org>:
You have taken responsibility. (Wed, 19 Sep 2012 06:33:17 GMT) Full text and rfc822 format available.

Notification sent to Charles Plessy <plessy@debian.org>:
Bug acknowledged by developer. (Wed, 19 Sep 2012 06:33:17 GMT) Full text and rfc822 format available.

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

From: Russ Allbery <rra@debian.org>
To: 654958-close@bugs.debian.org
Subject: Bug#654958: fixed in debian-policy 3.9.4.0
Date: Wed, 19 Sep 2012 06:32:10 +0000
Source: debian-policy
Source-Version: 3.9.4.0

We believe that the bug you reported is fixed in the latest version of
debian-policy, which is due to be installed in the Debian FTP archive.

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 654958@bugs.debian.org,
and the maintainer will reopen the bug report if appropriate.

Debian distribution maintenance software
pp.
Russ Allbery <rra@debian.org> (supplier of updated debian-policy 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: SHA256

Format: 1.8
Date: Tue, 18 Sep 2012 21:35:36 -0700
Source: debian-policy
Binary: debian-policy
Architecture: source all
Version: 3.9.4.0
Distribution: unstable
Urgency: low
Maintainer: Debian Policy List <debian-policy@lists.debian.org>
Changed-By: Russ Allbery <rra@debian.org>
Description: 
 debian-policy - Debian Policy Manual and related documents
Closes: 374029 571776 591791 641153 654958 661816 661933 663918 670429 676561
Changes: 
 debian-policy (3.9.4.0) unstable; urgency=low
 .
   * build-arch and build-indep are now mandatory targets in debian/rules,
     implementing the Technical Committee ruling in #629385.  Wording
     review by Jonathan Nieder, Jakub Wilk, and Roger Leigh.
     (Closes: #374029)
   * Resynchronize the archive section list with ftp-master, adding tasks.
     Patch from Charles Plessy.  (Closes: #670429)
   * Policy: Copyright files must be encoded in UTF-8
     Wording: Russ Allbery <rra@debian.org>
     Seconded: Guillem Jover <guillem@debian.org>
     Seconded: Salvatore Bonaccorso <carnil@debian.org>
     Seconded: Simon McVittie <smcv@debian.org>
     Closes: #661933
   * Policy: Prohibit deprecated < and > relations
     Wording: Jakub Wilk <jwilk@debian.org>
     Seconded: Cyril Brulebois <kibi@debian.org>
     Seconded: Russ Allbery <rra@debian.org>
     Closes: #663918
   * Policy: Document the Built-Using field
     Wording: Charles Plessy <plessy@debian.org>
     Seconded: Russ Allbery <rra@debian.org>
     Seconded: Ansgar Burchardt <ansgar@debian.org>
     Closes: #641153
   * Policy: Document the Vcs-* fields
     Wording: Charles Plessy <plessy@debian.org>
     Wording: Jonathan Nieder <jrnieder@gmail.com>
     Seconded: Russ Allbery <rra@debian.org>
     Seconded: Charles Plessy <plessy@debian.org>
     Seconded: Guillem Jover <guillem@debian.org>
     Closes: #654958
   * Policy: Document restrictions on the use of /run for wheezy
     Wording: Roger Leigh <rleigh@debian.org>
     Seconded: Charles Plessy <plessy@debian.org>
     Seconded: Russ Allbery <rra@debian.org>
     Closes: #676561
   * Policy: Rewrite shared library dependency policy to document symbols
     Wording: Russ Allbery <rra@debian.org>
     Wording: Jonathan Nieder <jrnieder@gmail.com>
     Seconded: Raphaël Hertzog <hertzog@debian.org>
     Seconded: Julien Cristau <jcristau@debian.org>
     Closes: #571776
   * Policy: Document generic and upstart-specific init system requirements
     Wording: Steve Langasek <steve.langasek@canonical.com>
     Seconded: Russ Allbery <rra@debian.org>
     Seconded: Adam D. Barratt <adam@adam-barratt.org.uk>
     Closes: #591791
   * Policy: Rely on triggers instead of calling update-mime
     Wording: Charles Plessy <plessy@debian.org>
     Seconded: Russ Allbery <rra@debian.org>
     Seconded: Guillem Jover <guillem@debian.org>
     Closes: #661816
Checksums-Sha1: 
 c728495994bbdabc43055dfbedfd662bba5eb069 1518 debian-policy_3.9.4.0.dsc
 4c6bc2d0eb510313e1b4a0d2a932f4182ffe6f91 704838 debian-policy_3.9.4.0.tar.gz
 ac9ff5a5987343a736fb45af52d3178bae30d37e 2147892 debian-policy_3.9.4.0_all.deb
Checksums-Sha256: 
 c6dbad5976931268283c02903cf0dc3f3bb8dfc86710cab462e0e6c19aab1407 1518 debian-policy_3.9.4.0.dsc
 01ae1a19f7a251dd5c2b078736427f33f04c5f7e38308f874345f1e3e194dca5 704838 debian-policy_3.9.4.0.tar.gz
 c6e22f66e4cd38cbfac944bfebb41fa5608604326c6ecb9dbbd2213f5372ebbd 2147892 debian-policy_3.9.4.0_all.deb
Files: 
 e5683a409d1f740582e960158152b4ba 1518 doc optional debian-policy_3.9.4.0.dsc
 33eafa60a7c79f827adaa1bdb0cdcf83 704838 doc optional debian-policy_3.9.4.0.tar.gz
 2c5c278e5035e26489c3ae76f8c428d2 2147892 doc optional debian-policy_3.9.4.0_all.deb

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

iQEcBAEBCAAGBQJQWVEqAAoJEH2AMVxXNt51CfcH/226voYDWjhFjwJJh61d0XBI
3JRRYNqF7rZ59zl4kwEX+QFe/CoKnX1rEceBb9g3cCJ/AO6vU8Z+hhGnpr4eus1v
2BKhO4E8S6vqjtWfiXHIUmkIlGQeuxY3aBMWNZPgQzqEz9Skrc3aDel3zuuiKehE
fTk8Kse0hwTGp5h9nVaXawdZEPKFhcQT2NrhhTE/VmTHuC1EzUTcjOUDeu8tM2xy
r6Zjytz43qqvWinUQNYQXOtjt2zAVV0dw6T9nWcssXOSTD1EZLbfAbaJw9m1VG6G
B9BRhz5xs334/DktrgDw2gKjb4IF2tI3lIPRj12OuGErR+lChgZr4egrA+xyBwM=
=SP2c
-----END PGP SIGNATURE-----




Bug archived. Request was from Debbugs Internal Request <owner@bugs.debian.org> to internal_control@bugs.debian.org. (Mon, 03 Jun 2013 08:40:58 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: Sat Apr 19 06:40:35 2014; Machine Name: beach.debian.org

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