All in all, it seems like this would work better as a microformat
inline, in the section. Perhaps leave it in the head just for
the case where the repository is the one used to generate this page?

Why? (1) According to microformats.org, microformats are intended to be
human readable. Most of what's in the isn't shown to most
humans. (2) If a page describes multiple projects with multiple
repositories, this would allow the descriptions to be linked to the
repos (through HTML containment).

I agree, I had forgotten that supported a type attribute, so the same info can be fit in there:

<a rel="vcs" type="git" href="git://example.org/foo.git" title="git repository">git://example.org/foo.git</a>

The only problem with this form is it uses a URI form that the browser will be unable to follow in a visible link. --Joey

I would be really interested to see the protocol name torn out of the rel - I don't think it really belongs there. In microformats I think you could get away with generally using class="vcs-git", and rel="vcs", but I'm not sure what the best practices are. --MarkTraceur

In fact I think we should not use the type attribute unless there are valid MIME types we could use to accurately represent the types we want (I had temporarily forgotten what the type attribute was for, last night, but now I'm sane again), so maybe class values are the "better" option for now. --MarkTraceur

In the "Multiple Repositories" section, why leave the rules for
divining which repository is writable up to the client? Seems like a
bit of metadata would help ensure consistent treatment by all clients.

To support multiple repositories, a client also has to choose between eg, http:// and git://. So it seems that the client is going to need to have some repo-type-specific smarts anyway.

It's also possible to have multiple mirrors of a repository, and the client may want to choose between those for the user.

Also, the only place I could see to encode anon/auth info is in the type, and overloading it with multiple bits of info ("git:anon"?) seemed a bit complex.

Finally, there's always the potential for a VCS to have more complex auth methods than simply an anonymous and an authenticated repo. So including it in the spec felt wrong. --Joey


We need an URI format for CVS.

<link rel="vcs" type="cvspserver" href=":pserver:user:password@example.org:/home/cvsroot:foomodule" title="foo cvs repository" />
<link rel="vcs" type="anoncvs" href=":ext:_anoncvs@anoncvs.mirbsd.org:/cvs:mksh" title="mksh source repository" /><!-- note: no password here -->

The syntax of the “href” part is: <cvsmethod>:<modulepath> (both are mandatory); cvsmethod can be

  • :pserver:[user[:password]@]hostname:pathtocvsroot
  • [:ext:][user[:password]@]hostname:pathtocvsroot

i.e. any valid “cvs -d” argument. Note that some, like the Kerberos authenticated one, don't make sense in this environment. I don't know what "user" should default to (probably "anoncvs", as it's most widely used).

The fact that it's been 20 years and nobody has come up with an URI form for CVS, makes me inclined not to bother. (That and being happy to see it die and never wanting to check out a CVS repo again ;-)

Anyway, I'd like to keep the type simple, one per VCS type, so attempts to do this should include whether it's pserver or anoncvs in the URI part. --Joey

Another option were to separate cvsmethod and modulepath with a space instead of a colon, like in the debian/control files, but then, who says that the pathtocvsroot cannot contain any spaces? So I chose the colon, since that'd be hard to use anyway. Note a slash is not possible, since both pathtocvsroot and modulepath can contain it.

Opinions?
--mirabilos

Even ignoring New URI Schemes Considered 99% Harmful, the above isn't in the syntax of a URI, and href is defined to be a URI. If you wanted to invent URI schemes for this I'd say that cvspserver://user:pass@host/pathtocvsroot?modulepath and cvsext://user:pass@host/pathtocvsroot?modulepath would be more appropriate.

Actually, href is preferred to be an URI (in this microformat), but luckily most modern VCS systems are sane enough to use URIs (though they do make up new schemes ;)

I agree, those URIs for cvs look more appropriate if something has to be made up. --Joey

Your microformat might only "prefer" the href attribute of <link> to be a URI, but the semantics of HTML/XHTML require it. I'm not sure that :pserver:... actually matches any of the productions in RFC 3986 URI Generic Syntax (because it happens to start with a colon) but if it's valid at all, then the only interpretation I can see is as a relative URI path (i.e. "filename"), relative to the address of the document. That's how Firefox interprets it, at least; it's the same failure mode as the common <a href="www.example.com">.

If you want something that can be not-a-URI, perhaps <meta name="vcs" content="cvs :pserver:blahblah"> would be more appropriate. --smcv

But don't just take my word for it, there is a procedure for registering URI schemes...

-- smcv


I'd really like to have support for human-readable "browse" pages. Probably this would just consist of adding a "browse" type to the spec. I suspect it would look like this:

<link href="https://git.gitorious.org/stattr/stattr.git" rel="vcs" type="git" />
<link href="https://gitorious.org/stattr/stattr" rel="vcs" type="browse" />

I would also appreciate a way to signify one project or another, useful when multiple different projects are represented on a page. For example, MediaWiki is considering printing human-readable documentation about source code for all extensions on a wiki - it would be great to print machine-readable ones too. e.g.

<div class="vcs-project">
    <span class="vcs-project-name">MediaWiki</span>:
    <a href="https://git.wikimedia.org/summary/mediawiki%2Fcore" rel="vcs" type="browse">Source</a> |
    <a href="https://git.wikimedia.org/git/mediawiki/core.git" rel="vcs" type="git">Repository</a>
</div>
<div class="vcs-project">
    <span class="vcs-project-name">WikiEditor</span>:
    <a href="https://git.wikimedia.org/summary/mediawiki%2Fextensions%2FWikiEditor" rel="vcs" type="browse">Source</a> |
    <a href="https://git.wikimedia.org/git/mediawiki/extensions/WikiEditor.git" rel="vcs" type="git">Repository</a>
</div>

Some thoughts :) --MarkTraceur