Right… sorry forgot about this @seancorfield. I had a peek at the cljdoc sources with regards to what revision it chooses. If I grok this correctly, in medium strokes: 1. Cljdoc starts off an import with project artifact coordinates, for example com.github.seancorfield/depstar version 2.1.267. 2. Cljdoc will check the project’s git repo for a git tag matching the artifact version. It will favour the raw version, else the version prefixed with v. In our example, 2.1.67 else v2.1.67. 3. At import time, cljdoc favours the pom.xml ’s project/scm/tag, it does not care if it is a git sha or a git tag. If there is no project/scm/tag it looks like it falls back to the git version tag (from step 2). 4. At render time, when linking back to the git repo (for source code or articles that are not imported), cljdoc favours the git version tag (from step 2). I should double check this all by running some tests. I think my confusion when last looking at this was around the git version tag. If I have specified a project/scm/tag, I wondered why cljdoc would use the git version tag (from step 2). My guess was that, at least partly, it makes for a more informative/readable URL when pointing back to the repo.

(I don’t think any of this helps with source libs, but good to understand the current mechanics).

Thanks, @lee! I had tried to trace through the code and I had been a little puzzled at what seemed like discrepancies in steps 2, 3, and 4, but as you say, there are "reasons" for what it is doing.

The bottom line is that for libraries that need to refer to a tag and SHA in their docs, they're always going to need to build cljdoc from a version that is "after" the tag. I wonder if a possible solution to this would be to have cljdoc understand a convention in tags/versions where a library could be released at a particular tag and SHA, could then update all of its docs to reference that tag/SHA, and could then tag the project with something like <version>.cljdoc and have cljdoc perform the import from that tag but still just use <version> everywhere (except step 4, linking to <version>.cljdoc, so that the state of the GH repo reflects the imported/generated docs?

The "nice" thing about that would be that maintainers could make doc-only updates, force move their .cljdoc tag, and then ask cljdoc to re-import the project...?

Yeah @seancorfield, I like your idea of an explicit <version>.cljdoc tag. It's clear in its intent and not magical. And like you say, has that additional "nice" benefit.