Add support for VCS Autodiscovery

[oliverpool]

I stumbled upon a RFC for generic VCS Autodiscovery: https://git.sr.ht/~ancarda/vcs-autodiscovery-rfc/tree/HEAD/RFC.md which add a couple of meta tags:

<meta content="git" name="vcs"/>
<meta content="master" name="vcs:default-branch"/>
<meta content="https://git.sr.ht/~ancarda/vcs-autodiscovery-rfc" name="vcs:clone"/>
<meta content="[email protected]:~ancarda/vcs-autodiscovery-rfc" name="vcs:clone"/>
<meta content="https://git.sr.ht/~ancarda/vcs-autodiscovery-rfc" name="forge:summary"/>
<meta content="https://git.sr.ht/~ancarda/vcs-autodiscovery-rfc/tree/{ref}/item/{path}" name="forge:dir"/>
<meta content="https://git.sr.ht/~ancarda/vcs-autodiscovery-rfc/tree/{ref}/item/{path}" name="forge:file"/>
<meta content="https://git.sr.ht/~ancarda/vcs-autodiscovery-rfc/blob/{ref}/{path}" name="forge:rawfile"/>
<meta content="https://git.sr.ht/~ancarda/vcs-autodiscovery-rfc/tree/{ref}/item/{path}#L{line}" name="forge:line"/>

I think it would be a nice addition to vangen.

If you agree, I can try to craft a PR!

---

Support is not widespread yet, but https://godocs.io/ supports it.

cc @ancarda (author of the RFC)

[leighmcculloch]

This looks very interesting. How would vangen change to use the autodiscovery?

[oliverpool]

I think vangen just needs to generate those tags as well (and add the relevant configuration in the json).

I can craft a PR in the next days if you want.

[leighmcculloch]

I think given the small number of VCS services, it will probably keep the logic in vangen simpler to maintain if we just hardcode any that are missing. Is there a software VCS that you'd like to add support to?

[oliverpool]

I think we should split at least the forge type and forge URL. Forge types:

• gitea
• sourcehut
• gitlab
• github

Forge URLs:

• gitea.com, codeberg.org, …
• git.sr.ht
• gitlab.com, framagit.org, …
• github.com

[leighmcculloch]

How would that be used?

[oliverpool]

Here is a config example, oriented towards supporting vcs (as-is it is a breaking change, but it can surely be adapted to be non-breaking):

Full custom example (but you prefer not to offer such a solution I understand).

{
  "domain": "example.com",
  "docsDomain": "pkg.go.dev",
  "index": true,
  "repositories": [
    // full custom example
    {
      // unrelated changes, closer to the go vocabulary
      "module": "pkg3",
      "packages": ["subpkg1"],

      // vcs tag
      "vcs": {
        "type": "git", // required
        "defaultBranch": "main", // optional
        "clone": [
          "https://rfc.example.com/repositories/go-pkg3.git",
          "ssh://[email protected]/repositories/go-pkg3"
        ]
      },
      "forge": {
        // custom definition
        "rawfile": "https://rfc.example/{path}?ref={ref}&raw=1",
        "file": "https://rfc.example/{path}?ref={ref}",
        "dir": "https://rfc.example/{ref}/{path}",
        "summary": "https://rfc.example/my-cool-project",
        "line": "https://rfc.example/tree/{ref}/item/{path}#L{line}"
      }
    }
  ]
}

Minimal example, just adding a forgeSoftware key

{
  "domain": "example.com",
  "docsDomain": "pkg.go.dev",
  "index": true,
  "repositories": [
    // "smart" example
    {
      // unrelated changes, closer to the go vocabulary
      "module": "pkg3",
      "packages": ["subpkg1"],

      // vcs tag
      "forgeSoftware": "gitea", // git.sr.ht, gitlab, github
      "url": "https://rfc.example.com/username/go-pkg3"

      /*
      "vcs": {
        "type": "git", (because gitea)
        "clone": ["https://rfc.example.com/username/pkg3.git"] // url+".git"
      },
      "forge": {
        //rawfile, file, dir, summary, line will be computed automatically
      }
      */
    }
  ]
}

Using forgeSoftware and url, all the attributes can be computed automatically (except defaultBranch).
(forgeSoftware could also be named platform)

[oliverpool]

I implemented my own package to generate the go documentation under the vanity URL: https://code.pfad.fr/vanitydoc, which implements the VCS Autodiscovery meta tags.

The package regarding autodiscovery is documented here: https://code.pfad.fr/vanitydoc/autodiscovery

It only support generating the documentation of a given module (so the index has to be curated manually, opposite to vangen)