Published February 28th, 2020
A large number of third party tools integrate into popular software forges such as GitHub and GitLab, offering developers and their end-users abilities that the forge itself does not implement. One common example is "README shields" that integrate with a package hosting service, and displays license information, download counts, and other statistics that are relevant to developers and end-users.
Unfortunately, many of these tools support a limited number of well-known forges - such as GitHub and GitLab - and do not support self-hosted instances of these platforms. This increases friction for those wanting to self-host and reduces the appeal of alternative platforms. Long term, this may pose a very real threat to computing if all open source code is hosted by a few large companies.
This RFC takes a step towards a standard that may, for a variety of tools, open them up to being used on self-hosted instances of supported forges as well as brand new players in the source code hosting space.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
Section 4 describes meta tags that are used for this standard. The content
attribute MAY contain one or more variables, which are wrapped in a
character and are lowercase.
%branch% is the name of a "branch" or a similar named reference concept.
%path% is the path to a file or directory without a leading slash. For
docs/README.md (file) or
There is only one required meta tag,
vcs which indicates the Version
Control System being used. This tag MAY have the following values, but is not
an exhaustive list. Software MUST be able to gracefully handle unknown values:
bzr(GNU Bazaar) bazaar.canonical.com
svn(Apache Subversion) subversion.apache.org
Here is an example tag:
<meta name="vcs" content="git" />
This tag MUST be used exactly once. Software consuming pages MUST error if this tag is used more than once.
The content of this tag MUST not include spaces, commas, semicolons, or
anything to otherwise indicate a list. Multiple version control systems for the
same project (on the same HTML page) is not supported. Software consuming pages
SHOULD error if space, colon, or semicolon is present in the content attribute
If the version control system has the concept of "branches", where different
versions of the code may live, the
default-branch key is used for this
<meta name="vcs:default-branch" content="master" />
If the software forge allows a raw file to be retrieved with a deterministic
rawfile key is used for this purpose. Here, "deterministic"
means software can construct a URL to the file without having to have knowledge
about the file including it's size, creation timestamp, or hash.
<meta name="vcs:rawfile" content="https://rfc.example/%path%?ref=%branch%&raw=1" />
If the software forge allows a file to be shown to an end-user with some pretty
file key is used for this purpose. Like
rawfile (4.3), the
URI MUST be deterministic.
<meta name="vcs:file" content="https://rfc.example/%path%?ref=%branch%" />
<meta name="vcs:dir" content="https://rfc.example/%branch%/%path%" />
Software Forges MAY present one or more URIs using any scheme.
<meta name="vcs:clone" content="https://rfc.example/project.git" /> <meta name="vcs:clone" content="ssh://firstname.lastname@example.org:project" />
Clone URIs MAY use any scheme and MAY require authentication. If a repository is open to the public, Forges SHOULD present at-least one clone URI that does not require authentication. The unauthorized URI SHOULD be first.
Software that cannot understand a clone URI or was denied access SHOULD try the subsequent URIs before failing.