Skip to content

Formalize the default branch convention for snapshots

For now, each loader decides what convention it uses for branches. This makes working with our snapshots harder than it should be for our users.

One of the things we need to decide is what the default branch for snapshots is; this is useful e.g. when presenting data in the web ui or when trying to run a metadata indexer.

My proposal is the following:

  • the default branch for snapshots is defined to be HEAD.
    • if the concept of HEAD exists with the same name in the upstream VCS (f.e. git, svn), this branch should be a literal pointer to the corresponding archived object
    • if the concept of HEAD doesn't exist with the same name in the upstream VCS (f.e. mercurial), this branch should be an alias pointing at the default branch, named using the upstream VCS context (f.e. in the mercurial case, that would be an alias for the tip of the default branch)
    • if the concept of a default branch/version doesn't exist in the upstream VCS, no HEAD branch should exist in the snapshot

I'm not sure where this documentation should live; I think https://wiki.softwareheritage.org/index.php?title=Repository_snapshot_objects should be reintegrated in swh-docs.

Migrated from T1257 (view on Phabricator)