docs: improve versioning documentation

[HonkingGoose]

Changes:

Goals of the rewrite as stated by @rarkins:

• Improve https://github.com/renovatebot/renovate/blob/master/docs/usage/modules/versioning.md to make it clearer why/how versioning might need a manual setting
• Reduce the text in helm-values/readme.md and replace with a more generic statement.
• Add same generic statement to other managers which have a similar requirement (mostly docker-related ones which don't enforce semver)

Context:

We need to improve our documentation so that we're clearer on how to configure custom versioning, and why you would want/need to do that.

Documentation (please check one with an [x])

• I have updated the documentation, or
• No documentation update is required

How I've tested my work (please tick one)

I have verified these changes via:

• Code inspection only, or
• Newly added unit tests, or
• No new tests but ran on a real repository, or
• Both unit tests + ran on a real repository

[HonkingGoose]

Copy/pasting @rarkins comment so that we can discuss it here:

FWIW, changing the versioning can be an occasional requirement for many managers, so we don't want to entirely duplicate all info about "how to change versioning" into in every manager's individual documentation. But like in the case of helm when managers don't have a firmly established convention for versioning (e.g. unlike npm or pypi) then I think it's OK to add a note saying it may be a common requirement to manually specify versioning in this manager and link to a shared guide on versioning in general.

i.e. should it be mentioned explicitly in the helm-values manager? Yes. But it should be a link to a common versioning document and not a full description which is valid to other managers too.

It was a not a reasonable expectation that such a proprietary syntax as used by linuxserver.io could be automatically detected and definitely not the type of thing that should be raised as a bug.

[rarkins]

Changing versioning for extracted dependencies is not unique to helm-values. Instead we should find an existing versioning documentation page or create a new one that describes how and why you'd want to change versioning, and then in managers like helm-values we can just have a note like "There is no fixed versioning convention for helm charts or the Docker images they reference, so at times the default semver versioning may not work. Please see X for information of why and how to customize versioning per-dependency."

[HonkingGoose]

find an existing versioning documentation page or create a new one that describes how and why you'd want to change versioning,

Turns out we do have a versioning documentation page, but it's hidden behind a fold-out menu: Renovate docs -> Renovate Modules -> Versioning.
See: https://docs.renovatebot.com/modules/versioning/ for the page I'm talking about.

The sub-section are coming from https://github.com/renovatebot/renovate/tree/master/lib/versioning and sourced from readme.md files. helm-values does not have its own directory in that folder structure, I'm not sure if we want to have a new folder for "helm-values" there or not...

in managers like helm-values we can just have a note like "There is no fixed versioning convention for helm charts or the Docker images they reference, so at times the default semver versioning may not work. Please see X for information of why and how to customize versioning per-dependency."

I agree we should probably centralize the versioning information, instead of spreading it over a lot of sub-pages. 😄

[rarkins]

Turns out we do have a versioning documentation page, but it's hidden behind a fold-out menu: Renovate docs -> Renovate Modules -> Versioning.

If you think fold-out menus can be removed and users would benefit from showing all sub-options by default, then we can do that (or perhaps wait until the Docusaurus migration is done).

The "Configuring Versioning" section is kind of what I had in mind (I'd forgotten it existed). Let's improve it if necessary and then link to it from managers with inconsistent versioning conventions - especially Docker ones.

helm-values does not have its own directory in that folder structure, I'm not sure if we want to have a new folder for "helm-values" there or not...

The sub-menus are for versioning schemes (lib/versioning/) while helm-values is a manager (lib/manager/) so it's not applicable here.

[HonkingGoose]

If you think fold-out menus can be removed and users would benefit from showing all sub-options by default, then we can do that (or perhaps wait until the Docusaurus migration is done).

I think that showing the sub-options might be a good stop-gap for now, as that allows users to "stumble upon" something they don't yet know they want/need.

I've checked the Docusaurus v2 docs, and you can select which sub-pages it should fold/display in the sidebar: https://v2.docusaurus.io/docs/sidebar#expanded-categories-by-default

The "Configuring Versioning" section is kind of what I had in mind (I'd forgotten it existed). Let's improve it if necessary and then link to it from managers with inconsistent versioning conventions - especially Docker ones.

I'll go tinker with this PR to improve the existing "configuring versioning" section then. 😉

The sub-menus are for versioning schemes (lib/versioning/) while helm-values is a manager (lib/manager/) so it's not applicable here.

Okay, so that's not the right place, I'll stay away from doing things in this folder then.

[rarkins]

1. Improve https://github.com/renovatebot/renovate/blob/master/docs/usage/modules/versioning.md to make it clearer why/how versioning might need a manual setting
2. Reduce the text in helm-values/readme.md and replace with a more generic statement.
3. Add same generic statement to other managers which have a similar requirement (mostly docker-related ones which don't enforce semver)

[HonkingGoose]

• Improve https://github.com/renovatebot/renovate/blob/master/docs/usage/modules/versioning.md to make it clearer why/how versioning might need a manual setting

• Reduce the text in helm-values/readme.md and replace with a more generic statement.

• Add same generic statement to other managers which have a similar requirement (mostly docker-related ones which don't enforce semver)

We still need to do the last thing in this list: "Add same generic statement to other managers which have a similar requirement".

@rarkins Is there a list somewhere of those manager which are likely to need custom versioning as well? So that we can copy/paste the generic statement into their manager docs?

[rarkins]

It's only really ones in the Docker ecosystem for now - e.g. dockerfile, docker-compose

[HonkingGoose]

@rarkins I hope these are OK, I tried to determine if it's likely that you'll need to override the default versioning. I saw some other managers that also don't seem to follow SemVer, so I included those as well.

Feel free to suggest changes. 😉

[renovate-release]

🎉 This PR is included in version 24.96.0 🎉

The release is available on:

• GitHub release
• 24.96.0

Your semantic-release bot 📦🚀

[HonkingGoose]

Thanks for helping me out here, and for merging the work! 😄 ✨