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

[Jonathan Nieder <jrnieder@gmail.com>]

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>