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

[Russ Allbery]

Jonathan Nieder jrnie...@gmail.com writes:

 Thanks again for your help.  I've applied all suggested changes.
 Interdiff and updated patch attached.

Thanks, this has been applied for the next release.

-- 
Russ Allbery (r...@debian.org)   http://www.eyrie.org/~eagle/


-- 
To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org
with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org

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

[Jonathan Nieder]

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
 +  ttgit 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


-- 
To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org
with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org

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

[Russ Allbery]

Jonathan Nieder jrnie...@gmail.com writes:

 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

Looks good to me.  (Tiny grammar nit: publicly-accessible, but I can fix
that when committing.)

-- 
Russ Allbery (r...@debian.org)   http://www.eyrie.org/~eagle/


-- 
To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org
with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org

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

[Russ Allbery]

Ben Pfaff b...@cs.stanford.edu writes:

 Is a hyphen desirable there?
 http://en.wikipedia.org/wiki/Hyphen#Compound_modifiers says:

 In the 19th century, it was common to hyphenate
 adverb–adjective modifiers with the adverb ending in -ly.
 However, this has become rare.  For example, wholly owned
 subsidiary and quickly moving vehicle are unambiguous,
 because the adverbs clearly modify the adjectives: quickly
 cannot modify vehicle.  However, if an adverb can also
 function as an adjective, then a hyphen may be or should be
 used for clarity, depending on the style guide.[3] For
 example, the phrase more-important reasons (reasons that are
 more important) is distinguished from more important reasons
 (additional important reasons), where more is an adjective.
 Similarly, more-beautiful scenery (with a mass-noun) is
 distinct from more beautiful scenery.  (In contrast, the
 hyphen in a more-important reason/a more important reason
 is not necessary.)  The hyphen in little-celebrated paintings
 clarifies that one is not speaking of little paintings.

 By that logic, I would think that no hyphen is needed, because
 publicly cannot modify repository.

Oh, good call.  You're right; Jonathan's original is better.  I didn't
think through the adverb vs. adjective distinction.  There's no ambiguity
without the hyphen since publicly is an adverb.

-- 
Russ Allbery (r...@debian.org)   http://www.eyrie.org/~eagle/


--
To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org
with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org

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

[Ben Pfaff]

Russ Allbery r...@debian.org writes:

 Jonathan Nieder jrnie...@gmail.com writes:

 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

 Looks good to me.  (Tiny grammar nit: publicly-accessible, but I can fix
 that when committing.)

Is a hyphen desirable there?
http://en.wikipedia.org/wiki/Hyphen#Compound_modifiers says:

In the 19th century, it was common to hyphenate
adverb–adjective modifiers with the adverb ending in -ly.
However, this has become rare.  For example, wholly owned
subsidiary and quickly moving vehicle are unambiguous,
because the adverbs clearly modify the adjectives: quickly
cannot modify vehicle.  However, if an adverb can also
function as an adjective, then a hyphen may be or should be
used for clarity, depending on the style guide.[3] For
example, the phrase more-important reasons (reasons that are
more important) is distinguished from more important reasons
(additional important reasons), where more is an adjective.
Similarly, more-beautiful scenery (with a mass-noun) is
distinct from more beautiful scenery.  (In contrast, the
hyphen in a more-important reason/a more important reason
is not necessary.)  The hyphen in little-celebrated paintings
clarifies that one is not speaking of little paintings.

By that logic, I would think that no hyphen is needed, because
publicly cannot modify repository.

(I am no expert on English.)


--
To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org
with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org

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

[Bernhard R. Link]

 +   tag
 + ttVcs-Arch/tt, ttVcs-Bzr/tt (Bazaar), ttVcs-Cvs/tt,
 + ttVcs-Darcs/tt, ttVcs-Git/tt, ttVcs-Hg/tt
 + (Mercurial), ttVcs-Mtn/tt (Monotone), ttVcs-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
 +   ttgit 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?

cvs: a identifier suiteable for cvs -d (i.e. usually starting with :pserver:),
followed by an optional module name (seperated by a space).

I think it might also make sense to explicitly request that the fields should
describe an anonymous checkout.

Bernhard R. Link


-- 
To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org
with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org

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

[Guillem Jover]

Hi!

On Thu, 2012-07-12 at 22:51:12 -0500, Jonathan Nieder wrote:
 Thanks again for your help.  I've applied all suggested changes.
 Interdiff and updated patch attached.

Seconded.

thanks,
guillem


signature.asc
Description: Digital signature

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

[Russ Allbery]

Jonathan Nieder jrnie...@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
   itemqref id=sourcebinarydepsttBuild-Depends/tt et 
 al/qref/item
   itemqref 
 id=f-Standards-VersionttStandards-Version/tt/qref 
 (recommended)/item
   itemqref id=f-HomepagettHomepage/tt/qref/item
 + itemqref id=f-VCS-fieldsttVCS 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
ttVcs-Browser/tt, ttVcs-Git/tt, et al.?  (Git because it's the
most commonly-used one, IIRC.)

 /list
   /p
  
 @@ -2728,6 +2729,7 @@ Package: libc6
 itemqref id=f-ChecksumsttChecksums-Sha1/tt
 and ttChecksums-Sha256/tt/qref (recommended)/item
 itemqref id=f-FilesttFiles/tt/qref (mandatory)/item
 +   itemqref id=f-VCS-fieldsttVCS 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
 +   headingVersion 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
 +   tagttVcs-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
 + ttVcs-Arch/tt, ttVcs-Bzr/tt (Bazaar), ttVcs-Cvs/tt,
 + ttVcs-Darcs/tt, ttVcs-Git/tt, ttVcs-Hg/tt
 + (Mercurial), ttVcs-Mtn/tt (Monotone), ttVcs-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
 +   ttgit 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 (r...@debian.org)   http://www.eyrie.org/~eagle/



-- 
To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org
with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org

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

[Jonathan Nieder]

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 @@
itemqref id=sourcebinarydepsttBuild-Depends/tt et 
al/qref/item
itemqref 
id=f-Standards-VersionttStandards-Version/tt/qref (recommended)/item
itemqref id=f-HomepagettHomepage/tt/qref/item
-   itemqref id=f-VCS-fieldsttVCS fields/tt/qref/item
+   itemqref id=f-VCS-fieldsttVcs-Browser/tt, 
ttVcs-Git/tt, et al./qref/item
  /list
/p
 
@@ -2724,12 +2724,12 @@
  itemqref id=f-UploadersttUploaders/tt/qref/item
  itemqref 
id=f-DM-Upload-AllowedttDM-Upload-Allowed/tt/qref/item
  itemqref id=f-HomepagettHomepage/tt/qref/item
+ itemqref id=f-VCS-fieldsttVcs-Browser/tt, ttVcs-Git/tt, 
et al./qref/item
  itemqref 
id=f-Standards-VersionttStandards-Version/tt/qref (recommended)/item
  itemqref id=sourcebinarydepsttBuild-Depends/tt et 
al/qref/item
  itemqref id=f-ChecksumsttChecksums-Sha1/tt
  and ttChecksums-Sha256/tt/qref (recommended)/item
  itemqref id=f-FilesttFiles/tt/qref (mandatory)/item
- itemqref id=f-VCS-fieldsttVCS 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
  tagttVcs-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
  ttgit clone/tt command.  If no branch is specified, the
  packaging should be on the default branch.
/p
From: Charles Plessy ple...@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

[jrnie...@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 @@ 

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

[Russ Allbery]

Jonathan Nieder jrnie...@gmail.com writes:

 Thanks again for your help.  I've applied all suggested changes.
 Interdiff and updated patch attached.

Looks good to me -- seconded.

-- 
Russ Allbery (r...@debian.org)   http://www.eyrie.org/~eagle/



-- 
To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org
with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org

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

[Charles Plessy]

Le Sun, Jul 08, 2012 at 08:19:12PM -0500, Jonathan Nieder a écrit :
 
 My feedback got no replies, so I can only assume that everyone was so
 awestruck by the suggestions that they were lost for words.

... or assume holidays :)

Thanks a lot for the revised patch.  From my point of view, it is consensual
and ready for being applied, so I second it.

Have a nice day,

-- 
Charles
Tsurumi, Kanagawa, Japan



--
To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org
with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org

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

[Jonathan Nieder]

Charles Plessy wrote:

 Would the following patch be acceptable now ?

My feedback got no replies, so I can only assume that everyone was so
awestruck by the suggestions that they were lost for words.

Here's an updated patch.  Improvements welcome.

Looking forward to your thoughts,
Jonathan
From: Charles Plessy ple...@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

[jrnie...@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 ]
---
 policy.sgml |   48 
 1 file changed, 48 insertions(+)

diff --git a/policy.sgml b/policy.sgml
index 52dbb26a..371123e1 100644
--- a/policy.sgml
+++ b/policy.sgml
@@ -2631,6 +2631,7 @@ Package: libc6
itemqref id=sourcebinarydepsttBuild-Depends/tt et 
al/qref/item
itemqref 
id=f-Standards-VersionttStandards-Version/tt/qref (recommended)/item
itemqref id=f-HomepagettHomepage/tt/qref/item
+   itemqref id=f-VCS-fieldsttVCS fields/tt/qref/item
  /list
/p
 
@@ -2728,6 +2729,7 @@ Package: libc6
  itemqref id=f-ChecksumsttChecksums-Sha1/tt
  and ttChecksums-Sha256/tt/qref (recommended)/item
  itemqref id=f-FilesttFiles/tt/qref (mandatory)/item
+ itemqref id=f-VCS-fieldsttVCS fields/tt/qref/item
/list
/p
 
@@ -3737,6 +3739,52 @@ Checksums-Sha256:
details.
  /p
/sect1
+
+   sect1 id=f-VCS-fields
+ headingVersion 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.
+
+   taglist
+ tagttVcs-Browser/tt/tag
+ item
+   p
+ HTTP URL of a web interface for browsing the repository.
+   /p
+ /item
+
+ tag
+   ttVcs-Arch/tt, ttVcs-Bzr/tt (Bazaar), ttVcs-Cvs/tt,
+   ttVcs-Darcs/tt, ttVcs-Git/tt, ttVcs-Hg/tt
+   (Mercurial), ttVcs-Mtn/tt (Monotone), ttVcs-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
+   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
+ ttgit 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

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

[Charles Plessy]

Le Wed, May 09, 2012 at 08:32:26PM +0200, Bernhard R. Link a écrit :
 * Bernhard R. Link brl...@debian.org [120108 14:03]:
  * Russ Allbery r...@debian.org [120107 20:42]:
   Bernhard R. Link brl...@debian.org writes:
Something that was only added to git after that discussion was already
running for a while is git-clone's -b. Sadly
  
Vcs-Git: git://git.eyrie.org/kerberos/webauth.git -b squeeze
  
does not work as debcheckout is not word splitting the argument, but the
error message at least cites a command one can just copy to the shell
and it will work.
  
   I wonder if the debcheckout developers would be willing to adopt this
   syntax, since that seems like a nice solution.
 
  I just submitted http://bugs.debian.org/655085 with a patch.
 
 The patch was applied to debcheckout, so Vcs-Git: can now specify
 a branch to use.

Thanks a lot !

Would the following patch be acceptable now ?

Have a nice day,

-- 
Charles Plessy
Tsurumi, Kanagawa, Japan
From c1d7640216e9d155dedb2fbdeee4bbc0ea6f305a Mon Sep 17 00:00:00 2001
From: Charles Plessy ple...@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 file changed, 38 insertions(+)

diff --git a/policy.sgml b/policy.sgml
index 52dbb26..64228a9 100644
--- a/policy.sgml
+++ b/policy.sgml
@@ -2631,6 +2631,7 @@ Package: libc6
 	itemqref id=sourcebinarydepsttBuild-Depends/tt et al/qref/item
 	itemqref id=f-Standards-VersionttStandards-Version/tt/qref (recommended)/item
 	itemqref id=f-HomepagettHomepage/tt/qref/item
+	itemqref id=f-VCS-fieldsttVCS fields/tt/qref/item
 	  /list
 	/p
 
@@ -2728,6 +2729,7 @@ Package: libc6
 	  itemqref id=f-ChecksumsttChecksums-Sha1/tt
 	  and ttChecksums-Sha256/tt/qref (recommended)/item
 	  itemqref id=f-FilesttFiles/tt/qref (mandatory)/item
+	  itemqref id=f-VCS-fieldsttVCS fields/tt/qref/item
 	/list
 	/p
 
@@ -3737,6 +3739,42 @@ Checksums-Sha256:
 	details.
 	  /p
 	/sect1
+
+	sect1 id=f-VCS-fields
+	  headingVersion 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
+	  tagttVcs-Browser/tt/tag
+	  item
+		p
+		  HTTP URL of a web-browsable repository.
+		/p
+	  /item
+
+	  tag
+		ttVcs-Arch/tt, ttVcs-Bzr/tt (Bazaar), ttVcs-Cvs/tt,
+		ttVcs-Darcs/tt, ttVcs-Git/tt, ttVcs-Hg/tt
+		(Mercurial), ttVcs-Mtn/tt (Monotone), ttVcs-Svn/tt
+		(Subversion)
+	  /tag
+	  item
+		p
+		  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 ttgit clone/tt command.  More than one
+		  different VCS may be specified for the same package.
+		/p
+	  /item
+	/taglist
+	  /p
+	/sect1
   /sect
 
   sect
-- 
1.7.10

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

[Jonathan Nieder]

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
 +   headingVersion 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.

[...]
 +   tagttVcs-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 ttgit 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



-- 
To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org
with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org

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

[Bernhard R. Link]

* Bernhard R. Link brl...@debian.org [120108 14:03]:
 * Russ Allbery r...@debian.org [120107 20:42]:
  Bernhard R. Link brl...@debian.org writes:
   Something that was only added to git after that discussion was already
   running for a while is git-clone's -b. Sadly
 
   Vcs-Git: git://git.eyrie.org/kerberos/webauth.git -b squeeze
 
   does not work as debcheckout is not word splitting the argument, but the
   error message at least cites a command one can just copy to the shell
   and it will work.
 
  I wonder if the debcheckout developers would be willing to adopt this
  syntax, since that seems like a nice solution.

 I just submitted http://bugs.debian.org/655085 with a patch.

The patch was applied to debcheckout, so Vcs-Git: can now specify
a branch to use.

Bernhard R. Link



-- 
To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org
with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org

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

[Jonathan Nieder]

Russ Allbery wrote:

 Maybe we should just
 document them as they are and be explicit about the limitations, saying
 things like:

 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.

 If, over time, debcheckout and our package metadata starts making more
 explicit guarantees, we can always tighten the language later, but the
 above reflects the current state of the archive.

That sounds sensible to me.

Thanks,
Jonathan



-- 
To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org
with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org

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

[Steve Langasek]

On Sat, Jan 07, 2012 at 08:46:47AM -0800, Russ Allbery wrote:
  I wonder if something like

  Vcs-Git: git://git.eyrie.org/kerberos/webauth.git squeeze

  could be made to work.

 My understanding was that the debcheckout developers were not enthused
 about adding a syntax that Git upstream didn't support, but I think that's
 the only solution that anyone's come up with so far.

 On the other hand, it is kind of silly for them to be in such widespread
 use without Policy saying anything about them.  Maybe we should just
 document them as they are and be explicit about the limitations, saying
 things like:

 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.

 If, over time, debcheckout and our package metadata starts making more
 explicit guarantees, we can always tighten the language later, but the
 above reflects the current state of the archive.

I object to policy specifying any Vcs-* fields in a way that does not
uniquely identify a Debian packaging branch.  Running debcheckout for a
package only to then have to guess at random which of 20 branches is the one
containing the packaging I care about[1] is nonsense, and I don't think this
has any business being in policy in the absence of sensible semantics.  The
field should in all cases point to the right branch, not just the right
repository, and in the absence of an acceptable per-branch URI syntax, it
ought not be standardized at all.

Now, given that git seems to be the only widespread VCS with theis problem, I
wouldn't object to codifying Vcs- fields for the others in the meantime; but
some people might find it equally unpalatable to specify fields for
everything except git.

-- 
Steve Langasek   Give me a lever long enough and a Free OS
Debian Developer   to set it on, and I can move the world.
Ubuntu Developerhttp://www.debian.org/
slanga...@ubuntu.com vor...@debian.org

[1] E.g., Vcs-Git: git://git.debian.org/~lamont/util-linux.git


signature.asc
Description: Digital signature

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

[Charles Plessy]

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 ple...@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
 	itemqref id=sourcebinarydepsttBuild-Depends/tt et al/qref/item
 	itemqref id=f-Standards-VersionttStandards-Version/tt/qref (recommended)/item
 	itemqref id=f-HomepagettHomepage/tt/qref/item
+	itemqref id=f-VCS-fieldsttVCS fields/tt/qref/item
 	  /list
 	/p
 
@@ -2713,6 +2714,7 @@ Package: libc6
 	  itemqref id=f-ChecksumsttChecksums-Sha1/tt
 	  and ttChecksums-Sha256/tt/qref (recommended)/item
 	  itemqref id=f-FilesttFiles/tt/qref (mandatory)/item
+	  itemqref id=f-VCS-fieldsttVCS fields/tt/qref/item
 	/list
 	/p
 
@@ -3720,6 +3722,42 @@ Checksums-Sha256:
 	details.
 	  /p
 	/sect1
+
+	sect1 id=f-VCS-fields
+	  headingVersion 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
+	  tagttVcs-Browser/tt/tag
+	  item
+		p
+		  HTTP URL of a web-browsable repository.
+		/p
+	  /item
+
+	  tag
+		ttVcs-Arch/tt, ttVcs-Bzr/tt (Bazaar), ttVcs-Cvs/tt,
+		ttVcs-Darcs/tt, ttVcs-Git/tt, ttVcs-Hg/tt
+		(Mercurial), ttVcs-Mtn/tt (Monotone), ttVcs-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

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

[Steve Langasek]

On Sun, Jan 08, 2012 at 09:55:48PM +0900, Charles Plessy wrote:

 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.

Yes.  By the nature of svn, the Vcs-Svn URI always unambiguously refers to a
single branch (trunk is a branch).  It's *only* the Vcs-Git usage is
broken.

 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.

Policy is for documenting what *SHOULD* be done.  It doesn't matter if it's
10 or 1000 packages that are using Vcs-Git today; if the syntax is broken,
it shouldn't go in policy.

-- 
Steve Langasek   Give me a lever long enough and a Free OS
Debian Developer   to set it on, and I can move the world.
Ubuntu Developerhttp://www.debian.org/
slanga...@ubuntu.com vor...@debian.org


signature.asc
Description: Digital signature

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

[Bernhard R. Link]

* Russ Allbery r...@debian.org [120107 20:42]:
 Bernhard R. Link brl...@debian.org writes:
  Something that was only added to git after that discussion was already
  running for a while is git-clone's -b. Sadly

  Vcs-Git: git://git.eyrie.org/kerberos/webauth.git -b squeeze

  does not work as debcheckout is not word splitting the argument, but the
  error message at least cites a command one can just copy to the shell
  and it will work.

 I wonder if the debcheckout developers would be willing to adopt this
 syntax, since that seems like a nice solution.

I just submitted http://bugs.debian.org/655085 with a patch.
Hopfeully that either is accepted or gives some response what a
acceptable solution would need to look like...

Bernhard R. Link



-- 
To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org
with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org

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

[Jonathan Nieder]

Charles Plessy wrote:

 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

Git URLs deliberately represent a repository, not a branch.  That is
because branches and repositories for a package are simply different
notions in git (unlike in Subversion, where they are both described by
a path relative to the root of a repository shared by multiple
packages).  This is not specific to Git but is a feature shared by
CVS, for example.

To represent a branch in a remote repository, one generally uses a Git
URL, followed by a space, followed by the branch name.  This is the
syntax accepted by git pull:

git pull git://git.example.com/path/to/repo for-charles

And it is the syntax generated by pull requests with the git request-pull
command.

All that said, I'm happy with any delimiter for the Vcs-Git field, as
long as it is not too ugly and it works.  And regarding git, I am
happy to be proven wrong if someone has ideas that lead to a better
workflow without breaking existing users too much (file a bug report
when you find them.:)).

Hope that helps,
Jonathan



-- 
To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org
with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org

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

[Russ Allbery]

Steve Langasek vor...@debian.org writes:

 I object to policy specifying any Vcs-* fields in a way that does not
 uniquely identify a Debian packaging branch.  Running debcheckout for a
 package only to then have to guess at random which of 20 branches is the
 one containing the packaging I care about[1] is nonsense, and I don't
 think this has any business being in policy in the absence of sensible
 semantics.  The field should in all cases point to the right branch, not
 just the right repository, and in the absence of an acceptable
 per-branch URI syntax, it ought not be standardized at all.

While I'm sympathetic to this position, the concern that I have with going
this route is that what branch I care about is never going to be a
clearly-defined concept.  Is it the branch for unstable?  The latest
packaging, which may only be in experimental, or may not have been
uploaded at all?  Are you working on a stable update, in which case you
need another branch entirely?

This comes back to the basic problem that while putting this metadata in
the package is certainly convenient and made the metadata available
quickly, it has some inherent limitations since the VCS information is not
a property of the package itself.  Rather, it's a property of how the
package is being maintained, which can change without changing the
package.

Given the fundamental issue that there are multiple things you may want
(the latest stuff, the last uploaded stuff, the unstable stuff, even the
stable stuff), I don't see how we'll ever, for any VCS (not just Git), get
any better than here's the repository and you may have to do additional
work to figure out the right branch in the VCS-* headers.  As Charles
points out, you need an explanation for humans, not computers, in some
other location, such as README.source.

What we *can* do is identify the repository, so I think we should
seriously consider standardizing that and leave the explanation of the
branches to README.source.

 Now, given that git seems to be the only widespread VCS with theis
 problem, I wouldn't object to codifying Vcs- fields for the others in
 the meantime; but some people might find it equally unpalatable to
 specify fields for everything except git.

CVS has the same issue, not that it's widely used any more.  But even
Subversion has the broader problem that it's not at all clear which branch
to designate.

-- 
Russ Allbery (r...@debian.org)   http://www.eyrie.org/~eagle/



-- 
To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org
with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org

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

[Jonathan Nieder]

Steve Langasek wrote:

 Yes.  By the nature of svn, the Vcs-Svn URI always unambiguously refers to a
 single branch (trunk is a branch).

FWIW, I would be happy to see at least that documented.  (It would
provide a reason to propose this change in the eglibc package. :))



-- 
To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org
with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org

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

[James McCoy]

On Sun, Jan 08, 2012 at 09:50:32AM -0800, Russ Allbery wrote:
 Steve Langasek vor...@debian.org writes:
 
  I object to policy specifying any Vcs-* fields in a way that does not
  uniquely identify a Debian packaging branch.  Running debcheckout for a
  package only to then have to guess at random which of 20 branches is the
  one containing the packaging I care about[1] is nonsense, and I don't
  think this has any business being in policy in the absence of sensible
  semantics.  The field should in all cases point to the right branch, not
  just the right repository, and in the absence of an acceptable
  per-branch URI syntax, it ought not be standardized at all.
 
 While I'm sympathetic to this position, the concern that I have with going
 this route is that what branch I care about is never going to be a
 clearly-defined concept.  Is it the branch for unstable?  The latest
 packaging, which may only be in experimental, or may not have been
 uploaded at all?  Are you working on a stable update, in which case you
 need another branch entirely?

I have to agree with Russ here.  It's easy enough to change the Vcs-*
fields so they're appropriate for uploads to unstable or experimental,
but as soon as a package transitions out of unstable the field is
potentially out of date.

If there's a non-trivial branching policy, then that could be described
in README.source (or a new README.vcs since it's not directly related to
working with the source package).

This is more relevant for non-DVCS (like svn) since checking out an
entire project's repository instead of just the development branch can
take much more time and space.  The problem is that the exact VCS where
it is most beneficial to provide the most specific information are also
the ones where not having the correct information (e.g., still having
the URL for unstable when the package is in stable) makes the checkout
useless.

  Now, given that git seems to be the only widespread VCS with theis
  problem, I wouldn't object to codifying Vcs- fields for the others in
  the meantime; but some people might find it equally unpalatable to
  specify fields for everything except git.

Any VCS workflow which uses different branches for different releases
(or uploads to places other than unstable) is going to have this
problem.

-- 
James
GPG Key: 4096R/331BA3DB 2011-12-05 James McCoy james...@debian.org


signature.asc
Description: Digital signature

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

[Russ Allbery]

Jonathan Nieder jrnie...@gmail.com writes:
 Russ Allbery wrote:

 Also, for a Git repository, what do you do if the Debian packaging isn't
 on the master branch?  For example, for packages for which I'm also
 upstream, I do upstream development on the master branch and Debian
 packaging on a separate debian branch.

 I wonder if something like

   Vcs-Git: git://git.eyrie.org/kerberos/webauth.git squeeze

 could be made to work.

My understanding was that the debcheckout developers were not enthused
about adding a syntax that Git upstream didn't support, but I think that's
the only solution that anyone's come up with so far.

On the other hand, it is kind of silly for them to be in such widespread
use without Policy saying anything about them.  Maybe we should just
document them as they are and be explicit about the limitations, saying
things like:

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.

If, over time, debcheckout and our package metadata starts making more
explicit guarantees, we can always tighten the language later, but the
above reflects the current state of the archive.

-- 
Russ Allbery (r...@debian.org)   http://www.eyrie.org/~eagle/



-- 
To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org
with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org

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

[Russ Allbery]

Bernhard R. Link brl...@debian.org writes:

 Something that was only added to git after that discussion was already
 running for a while is git-clone's -b. Sadly

 Vcs-Git: git://git.eyrie.org/kerberos/webauth.git -b squeeze

 does not work as debcheckout is not word splitting the argument, but the
 error message at least cites a command one can just copy to the shell
 and it will work.

I wonder if the debcheckout developers would be willing to adopt this
syntax, since that seems like a nice solution.

-- 
Russ Allbery (r...@debian.org)   http://www.eyrie.org/~eagle/



-- 
To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org
with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org

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

[Charles Plessy]

Package: debian-policy
Version: 3.9.2.0
Severity: normal

Dear all,

now that thousands of pakcages use the VCS fields, I think that it is time to
document them in the Policy.  Please see the attached patch as a starting
point.

The Developers Reference already documents the VCS fields, and discusses
related points such as their use by the PTS.  I intentionally made the attached
patch very dry to avoid unnecessary overlaps.  If it is accepted, I will submit
a patch against the Def. Ref. to link to the Policy.

  
http://www.debian.org/doc/manuals/developers-reference/best-pkging-practices#bpp-vcs

Have a nice day,

-- 
Charles
>From 3d7f84e3b7b1c0d17bb2312d99273f261c042179 Mon Sep 17 00:00:00 2001
From: Charles Plessy 
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

---
 policy.sgml |   36 
 1 files changed, 36 insertions(+), 0 deletions(-)

diff --git a/policy.sgml b/policy.sgml
index c1ff4b4..babcf0f 100644
--- a/policy.sgml
+++ b/policy.sgml
@@ -2616,6 +2616,7 @@ Package: libc6
 	Build-Depends et al
 	Standards-Version (recommended)
 	Homepage
+	VCS fields
 	  
 	
 
@@ -2713,6 +2714,7 @@ Package: libc6
 	  Checksums-Sha1
 	  and Checksums-Sha256 (recommended)
 	  Files (mandatory)
+	  VCS fields
 	
 	
 
@@ -3720,6 +3722,40 @@ Checksums-Sha256:
 	details.
 	  
 	
+
+	
+	  Version Control System (VCS) fields
+
+	  
+	Debian source packages are increasingly developed using VCSs.  The
+	purpose of the following fields is to give the user an easy access
+	to the package's repository.
+
+	
+	  Vcs-Browser
+	  
+		
+		  HTTP URL of a web-browsable repository.
+		
+	  
+
+	  
+		Vcs-arch, Vcs-bzr (Bazaar), Vcs-cvs,
+		Vcs-darcs, Vcs-git, Vcs-hg
+		(Mercurial), Vcs-mtn (Monotone), Vcs-svn
+		(Subversion)
+	  
+	  
+		
+		  String identifying unequivocally the location of the
+		  repository for anonymous access.  The field name identifies
+		  the VCS.  More than one different VCS may be specified for the
+		  same package.
+		
+	  
+	
+	  
+	
   
 
   
-- 
1.7.7.3

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

[Jonathan Nieder]

Hi Charles,

Charles Plessy wrote:

 +   tag
 + ttVcs-arch/tt, ttVcs-bzr/tt (Bazaar), ttVcs-cvs/tt,
 + ttVcs-darcs/tt, ttVcs-git/tt, ttVcs-hg/tt
 + (Mercurial), ttVcs-mtn/tt (Monotone), ttVcs-svn/tt
 + (Subversion)
 +   /tag
 +   item
 + p
 +   String identifying unequivocally the location of the
 +   repository for anonymous access.  The field name identifies
 +   the VCS.  More than one different VCS may be specified for the
 +   same package.

If I keep my sources in svn, should I give a URL to the toplevel of the
repository (which is what one passes to git svn clone -s and allows
access to all branches) or one particular branch?  If a branch, which
branch, and should its content at the tip represent the last uploaded
version or is it allowed to be ahead of, behind, or even unrelated to
that?  Should the content at the tip match the uploaded package, or is
allowed to contain more, less, or some unrelated collection of files?

If I keep my sources using CVS, what is the format of the URL?  The
cvs package is an example.

What happens when the repository is moved or there is an outage?  Does
this represent a bug in the package like an email outage preventing
contact to the maintainer would?

Thanks and hope that helps,
Jonathan



-- 
To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org
with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org

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

[Russ Allbery]

Jonathan Nieder jrnie...@gmail.com writes:

 If I keep my sources in svn, should I give a URL to the toplevel of the
 repository (which is what one passes to git svn clone -s and allows
 access to all branches) or one particular branch?

For debcheckout to work properly, you want to specify a branch.

 If a branch, which branch, and should its content at the tip represent
 the last uploaded version or is it allowed to be ahead of, behind, or
 even unrelated to that?  Should the content at the tip match the
 uploaded package, or is allowed to contain more, less, or some unrelated
 collection of files?

Also, for a Git repository, what do you do if the Debian packaging isn't
on the master branch?  For example, for packages for which I'm also
upstream, I do upstream development on the master branch and Debian
packaging on a separate debian branch.

I've always found the Vcs-* headers a bit underspecified, or at least
limited.  (I'm fairly sure the answer to my question is that debcheckout,
which is the only real consumer of the Vcs-* headers that I know of other
than statistical analysis of types of repositories, just can't handle that
case at all.)

-- 
Russ Allbery (r...@debian.org)   http://www.eyrie.org/~eagle/



-- 
To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org
with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org