Bug#654958: debian-policy: Document VCS fields.
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
diff -u b/policy.sgml b/policy.sgml
--- b/policy.sgml
+++ b/policy.sgml
@@ -2631,7 +2631,7 @@
<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>
+ <item><qref id="f-VCS-fields"><tt>Vcs-Browser</tt>, <tt>Vcs-Git</tt>, et al.</qref></item>
</list>
</p>
@@ -2724,12 +2724,12 @@
<item><qref id="f-Uploaders"><tt>Uploaders</tt></qref></item>
<item><qref id="f-DM-Upload-Allowed"><tt>DM-Upload-Allowed</tt></qref></item>
<item><qref id="f-Homepage"><tt>Homepage</tt></qref></item>
+ <item><qref id="f-VCS-fields"><tt>Vcs-Browser</tt>, <tt>Vcs-Git</tt>, et al.</qref></item>
<item><qref id="f-Standards-Version"><tt>Standards-Version</tt></qref> (recommended)</item>
<item><qref id="sourcebinarydeps"><tt>Build-Depends</tt> et al</qref></item>
<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>
</list>
</p>
@@ -3746,13 +3746,13 @@
<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.
+ repository 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.
+ URL of a web interface for browsing the repository.
</p>
</item>
@@ -3767,13 +3767,14 @@
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.
+ 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 Git URL
- optionally followed by the word <tt>-b</tt> and the name of
- a branch in the indicated repository, like with the
+ 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>
From: Charles Plessy <plessy@debian.org>
Date: Sat, 7 Jan 2012 15:00:30 +0900
Subject: Document VCS fields, using Developers's Reference §6.2.5 for inspiration.
Closes: #654958
[jrnieder@gmail.com:
- declared repositories should be publicly accessible
- Vcs-Browser should point to a webapp
- Vcs-<system> should use the version control system's conventional syntax
- if multiple branches are used for packaging (e.g., "stable",
"testing", "sid"), any one of them will do
- for Vcs-Git, "-b <branch>" can be omitted when the intended branch is the
default branch
- list some Vcs-<foo> fields by name in the lists in §5.2 and §5.4
- declared repositories track development of the Debian source
package, not just the upstream code
- Vcs-Browser can be a web interface using any protocol (e.g., HTTPS
is fine)
- picking a good branch is optional
Thanks to Russ Allbery for several improvements to the text.]
---
policy.sgml | 49 +++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 49 insertions(+)
diff --git a/policy.sgml b/policy.sgml
index 52dbb26a..7d514921 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-Browser</tt>, <tt>Vcs-Git</tt>, et al.</qref></item>
</list>
</p>
@@ -2723,6 +2724,7 @@ Package: libc6
<item><qref id="f-Uploaders"><tt>Uploaders</tt></qref></item>
<item><qref id="f-DM-Upload-Allowed"><tt>DM-Upload-Allowed</tt></qref></item>
<item><qref id="f-Homepage"><tt>Homepage</tt></qref></item>
+ <item><qref id="f-VCS-fields"><tt>Vcs-Browser</tt>, <tt>Vcs-Git</tt>, et al.</qref></item>
<item><qref id="f-Standards-Version"><tt>Standards-Version</tt></qref> (recommended)</item>
<item><qref id="sourcebinarydeps"><tt>Build-Depends</tt> et al</qref></item>
<item><qref id="f-Checksums"><tt>Checksums-Sha1</tt>
@@ -3737,6 +3739,53 @@ 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 a publicly accessible
+ repository where the Debian source package is developed.
+
+ <taglist>
+ <tag><tt>Vcs-Browser</tt></tag>
+ <item>
+ <p>
+ URL of a web interface for browsing the repository.
+ </p>
+ </item>
+
+ <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>
+ <p>
+ More than one different VCS may be specified for the same
+ package.
+ </p>
+ </item>
+ </taglist>
+ </p>
+ </sect1>
</sect>
<sect>
--
1.7.10.4
Reply to: