💾 Archived View for markdain.net › project › vcs-autodiscovery › rfc.gmi captured on 2023-06-16 at 16:13:15. Gemini links have been rewritten to link to archived content
⬅️ Previous capture (2023-01-29)
-=-=-=-=-=-=-
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
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 lowercase and surrounded by `{` and `}` characters.
`{ref}` is the name of a "branch" or a similar named reference concept.
`{path}` is the path to a file or directory without a leading forward slash. Directories MUST end with a forward slash, files MUST NOT end with a forward slash.
The only exception to this rule is that the root directory MUST not be `/`, but rather an empty string.
Valid examples:
`{line}` is a line number or range of line numbers. Here, "number" means a non-negative, non-zero integer. Valid formats include:
Software forges implementing a tag with this variable MUST support the single number mode and SHOULD gracefully ignore ranges and lists if there is no support for that.
Software forges MAY error if a range is in descending order (example: `8-5`) or a list is in descending order (example: `9,8,7,5`).
There is only one required meta tag, `vcs` which indicates the Version Control System being used. The purpose of 4.1 is to facilitate repo cloning.
This tag MAY have the following values, but is not an exhaustive list. Software MUST be able to gracefully handle unknown values:
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 of a `vcs` tag.
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 purpose.
<meta name="vcs:default-branch" content="master" />
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://git@rfc.example: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.
Tags in 4.2 are to facilitate navigation around software forges.
If the software forge allows a raw file to be retrieved with a deterministic path, the `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="forge:rawfile" content="https://rfc.example/{path}?ref={ref}&raw=1" />
If the software forge allows a file to be shown to an end-user with some pretty printing, the `file` key is used for this purpose. Like `rawfile` (4.2.1), the URI MUST be deterministic.
<meta name="forge:file" content="https://rfc.example/{path}?ref={ref}" />
<meta name="forge:dir" content="https://rfc.example/{ref}/{path}" />
Links to an overview of the project. This may be hosted on a separate domain.
<meta name="forge:summary" content="https://rfc.example/my-cool-project">
If the software forge supports pretty printing a file with a highlighted line,
it is indicated this way:
<meta name="forge:line" content="https://rfc.example/tree/{ref}/item/{path}#L{line}">
The `{line}` variable is mandatory.