Currently

At build time

When cljdoc is analyzing a library's git repo, looks for:

• pom-revision - the artifact's pom <scm> <tag> (which can be anything comittish, long sha, tag, etc)
• version-tag - for artifact version 1.2.3 is looks for git tag 1.2.3 else v1.2.3

For analysis, if the pom-revision is not specified, cljdoc defaults to version-tag.

At render time

When cljdoc is fixing up HTML links and image refs back to GitHub (or other supported SCMs), it will always favour the version-tag even when the pom-revision was present at analysis time.

In effect, it can point back to a GitHub repo revision at render time that is different than the one used at build time.

So is this a problem?

Maybe not, but I've raised the issue because I found it confusing and wanted to give it some more thought.

I think cljdoc might be favouring the version-tag at render time for easier to grok URLs back to GitHub. A version in a URL is easier to quickly eyeball for correctness than a what could potentially be a long commit sha.

How could this go wrong for users? I don't think there is much chance for this causing problems.
A user tagging their repo with something that looks like a version tag that does not match a release seems unlikely.

A pom scm tag that specifies the version tag should be unaffected.
A pom scm tag that specifies a commit sha that differs from a found version tag seems unlikely.

Options

For the sake of this issue, let's forget that tags are mutable.
I don't think folks typically move their release tags?
And I don't think cljdoc should really be concerned if they do.

Off the top of my head:

1. Leave it, but document the behaviour in the author guide
2. Always favour the version tag if found at both build and render time
3. If pom scm tag was specified, use that at both build and render time
4. If pom scm tag was specified and version tag found and they are equivalent at build time, use version tag, else use the pom scm tag.

I think that making a change here would be more for cljdoc developers.
I've spent a chunk of time wondering why there is this potential mismatch.
Why burden other developers with this too?