Bug#654958: debian-policy: Document VCS fields.
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.
>From c6134f854762e7ce844a74c64a6591e1653ddf95 Mon Sep 17 00:00:00 2001
From: Charles Plessy <plessy@debian.org>
Date: Sat, 7 Jan 2012 15:00:30 +0900
Subject: [PATCH] =?UTF-8?q?Document=20VCS=20fields,=20using=20Developers's=20?=
=?UTF-8?q?Reference=20=C2=A76.2.5=20for=20inspiration.?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Closes: #654958
---
policy.sgml | 38 ++++++++++++++++++++++++++++++++++++++
1 files changed, 38 insertions(+), 0 deletions(-)
diff --git a/policy.sgml b/policy.sgml
index c1ff4b4..f2b7273 100644
--- a/policy.sgml
+++ b/policy.sgml
@@ -2616,6 +2616,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>
</list>
</p>
@@ -2713,6 +2714,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>
</list>
</p>
@@ -3720,6 +3722,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.
+
+ <taglist>
+ <tag><tt>Vcs-Browser</tt></tag>
+ <item>
+ <p>
+ HTTP URL of a web-browsable 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 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. More
+ than one different VCS may be specified for the same package.
+ </p>
+ </item>
+ </taglist>
+ </p>
+ </sect1>
</sect>
<sect>
--
1.7.8.2
Reply to: