How to specify alternative forge and mirrors?

[adulau]

Nowadays, it is increasingly difficult to identify the canonical forge and the available mirrors for an open source project.

How should this be expressed in publiccode.yml? In particular, is there a recommended way to distinguish between the authoritative repository and mirrors (backup)?

For example, we operate a ForgeJo instance that mirrors GitHub repositories we actively maintain. Can this relationship (canonical repository vs. mirror) be clearly and unambiguously expressed in the YAML file?

[bfabio]

For context: url always describes the repo it is in. If the publiccode.yml file is fetched from a different place, crawlers oughta reject it as invalid, it's basically hijacking.

Mirrors would have the same requirements as url: but they can't really be checked in the same way, since the publiccode.yml is fetched from a single URL. (as a sidenote: this is related with multi-repo projects with a single publiccode.yml, that we need to find an elegant solution for: #169)

But mirrors are verifiable, can be created by anyone and there can be many of them even that we don't know about, the simplest option might be to mention official mirrors in description, as an informational note.

After all, an unofficial mirror is no different from any other clone if the hash matches. WDYT?

[lsmith77]

@bfabio's concern about the authority model is the right one to solve — and I think it's resolvable without changing the authority semantics of url at all. The key is that mirrors would live inside the publiccode.yml at the canonical url, not in a file hosted at the mirror. The canonical file declares its own mirrors; no mirror can declare itself. The authority chain stays intact.

Concretely:

url: https://github.com/example/project  # canonical, unchanged — file lives here

mirrors:
  - url: https://codeberg.org/example/project  # endorsed by the canonical file
  - url: https://decommissioned.example.org/owner/project
    status: deprecated

# For forge migrations: previous canonical URLs, in chronological order.
# Lets catalogs resolve stale references without manual updates everywhere.
previousUrls:
  - https://old-forge.example.org/owner/project

previousUrls handles the migration case: once a project moves forges, the new publiccode.yml at the new url declares where it used to live, letting catalogs merge stale references. Full rationale and lifecycle coverage in this proposal.