Bug#654958: debian-policy: Document VCS fields.
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/>
Reply to: