Versions: clarify usage of Version.identifier and Version.verbose_name for stable and latest

[stsewd]

What's the problem this feature will solve?

Currently, we use identifier and verbose name depending on the version type, for example:

• For branches, identifier and verbose_name are the same (some old versions have origin/<branch name> as the identifier).
• For tags, the identifier is the commit hash, and verbose name is the tag name.
• For external versions, verbose name is the tag name and identifier is the commit hash.

All good, but things get confusing for latest and stable, since they can be a tag or a branch.

For latest, verbose name is latest, and the identifier is the branch or tag name. Identifier has also a special case where it can be None (this signals git to use the default cloned branch).

For stable, verbose name is stable and the identifier is the commit.

Describe the solution you'd like

A) Always save the name of the branch/tag for stable and latest as the identifier. And for the special case for latest where the identifier is None, check instead if the version is latest and if the project has the default branch set to None in order to use the default cloned branch. The identifier of latest will be updated after clone (git rev-parse --abbrev-ref HEAD can be used to get the branch name).

B) Use the branch/tag name as the verbose name for stable and latest and the commit as identifier. We can already identify the version as latest/stable by checking its slug and machine attribute. For latest having the identifier set to None, use the same solution as above.

Additional context

• Version in ReadTheDocs retains the tags commit ID preventing a rebuild based on the updated commit for the TAG  #10838
• Revert "Build: use tag name for checkout" #10887
• Stable build does not make git tag available during build #10715

[humitos]

How complex would be to refactor these fields and use names without ambiguities: commit and branch_name instead of identifier and verbose_name for example?

Or, if it's too complex to change the names, keep the names but remove the ambiguity from them: identifier will always be the commit hash and verbose_name will always be the branch/tag name. If we need more data than commit hash and branch/tag name to make other decisions, we can add extra fields: clone_default_branch (boolean) or similar. Would this be a problem?

The logic under versions have been pretty complicated and we have been changing lately (in particular with the new Git clone approach). I think that removing this ambiguity would be key to keep it clean and easy to maintain over time.

[stsewd]

Or, if it's too complex to change the names, keep the names but remove the ambiguity from them: identifier will always be the commit hash and verbose_name will always be the branch/tag name. If we need more data than commit hash and branch/tag name to make other decisions, we can add extra fields: clone_default_branch (boolean) or similar. Would this be a problem?

This is kind of option B. The only problem is that we will need to update all places that make use of verbose_name to use latest/stable instead if the version is machine created. Or introduce a new field, so we have identifier (commit), verbose_name (how the version is presented to the user), and ref_name (branch/tag name). This may be redundant, since verbose_nameand ref_name would be the same for all versions, except for latest/stable.