Bug#654958: debian-policy: Document VCS fields.

[Jonathan Nieder <jrnieder@gmail.com>]

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