[v1.0.0b] [Task] - Docs: Tag new Features with Version Info

[hay-kot]

What is the problem this task addresses?

There is some confusion with how documentation is published with nightly information and what is available in stable.

• [BUG] - OIDC Environment Variables not being used #3309

Proposed/Possible Solution(s)?

I suggest that we tag documentation sections with the release tag. I do this for Homebox.

You can see the code for that here

https://github.com/hay-kot/homebox/blob/main/docs/docs/tips-tricks.md#qr-codes

Basically, just add :octicons-tag-24: v0.9.0

[boc-the-git]

@hay-kot what value do you see being populated for "unreleased" items? The OIDC example.. in theory it could be added as v1.4.0, but that's not guaranteed.
Do you suggest just choosing the next minor version (e.g. 1.4.0) at the time someone raises their PR?

I accept anything is better than the current state, just trying to understand the intention :)

[hay-kot]

@boc-the-git

With what I've proposed there are two benefits I think. 1) We don't have to update or change how docs are deployed. I don't think Netlify has an easy way to only deploy on release so we'd likely have to move it back to GH pages or something to have it deploy only the released docs. 2) Publishing nightly docs is helpful when we ask folks to test stuff like OIDC. Just point them to the one docs URL.

Do you suggest just choosing the next minor version (e.g. 1.4.0) at the time someone raises their PR?

Yes, but I think that's pretty easy to determine. If you're adding a new section to the docs for a new feature, you know that your change is going to incur a minor version bump. I don't think there would be any instances where we would bump just the patch version and include a large section of documentation where the version would matter like it does here. These flags would only be for features in my mind.

--

The alternative would be to just publish new docs on a release, which isn't impossible so if there's some appetite to do it that way, I'm happy to look into it.

[boc-the-git]

The solution that popped into my head before reading your response, is that we could do something like how the image version tags in our sample compose files are handled.. we have people add their docs with a tag like NEXTVERSION or something, then when a release is done we use sed (or something) to set the actual version number.

But that is quite probably over-engineering it and I agree in 90%+ of scenarios there's going to be a minor version update for any change so substantial it involved new docs.