Default documentation version?

[finestructure]

I wonder if we need a way of allowing package authors to specify which documentation version we should resolve to by default.

For example, I've updated SPIManifest's docs a couple of times recently and each time I've ended up tagging a new patch release purely to update the docs – for the sole purpose that the default docs are showing the latest version.

Ideally I'd have liked to just update the docs on main and have them shown by default.

Arguably that's what patch versions are for and maybe it's just that SPIManifest is a bit special in that it's a package with limited functionality that exists mainly to host documentation.

But maybe there's a wider need to be able to control what doc version we present by default?

[heckj]

I think there's two primary flows here, with perhaps a longer tail of more arcane patterns. There's the "develop and release whatever is there on main" for fast, iterative development where a formal release # isn't much of a change or typically big steps. Then there's the "I've got this spread apart in pieces on the floor, refactoring - please don't rebuild the docs until I've cleaned it up, tagged it, and then display the last version I tagged while I do that again".

While most of what I do keeps my docs up to date and would love the "build main, call it good" - there's a few places more recently where I'd definitely prefer that the default version is the latest tagged version.

[daveverwer]

I see the use case, but I’m not too sure we should do it.

If we do add it, the choice in the config file should be between our three latest types: Default branch, latest stable release, and (possibly) latest pre-release, although I can’t see anyone using that last one! I don’t think it should be any more granular than that.

The additional flexibility is convenient, but if too many package authors choose main then we run the risk of what we show drifting away from functionality as well as documentation. I can see cases where a package author doesn’t want to push a release as they just fixed a typo. They find this option, and switch their package to default branch documentation. Then they completely forget they did that and a year later their documentation is out of sync with what functionality people get when they add the package.

I can see a case for it, but I think I like the simplicity of the way we have it right now.

I wonder if there’s a slight modification to the little banner we have when you land on an OLD version of documentation:

Something like this:

The hardest part of this for sure would be determining if the documentation has changed, and it’s probably not worth trying to figure that out, but I thought I’d throw the idea in the hat.