docs: improve versioning documentation (#9017)

docs/usage/modules/versioning.md

@@ -4,11 +4,27 @@ Once Managers have extracted dependencies, and Datasources have located availabl
 The "versioning" is different for each package manager, because different package managers use different versioning schemes.
 For example, `npm` uses`1.0.0-beta.1` and `pip` uses `1.0.0b1`.
 
-## Configuring Versioning
+## Why you might need to manually configure versioning
+
+Renovate interprets versions correctly out-of-the-box most of the time.
+It's impossible to automatically detect **all** versioning schemes, so sometimes you need to tell the bot what versioning scheme it should use.
 
 You can manually configure/override the `versioning` value for a particular dependency.
 You generally won't need to override the defaults for ecosystems which enforce a strict version scheme like `npm`.
-Configuring or overriding the default `versioning` can be helpful for ecosystems like Docker, where versioning is barely a "convention". e.g.
+
+Configuring or overriding the default `versionScheme` can be particularly helpful for ecosystems like Docker/Kubernetes/Helm, where versioning is barely a "convention".
+
+## General concepts behind overriding versioning
+
+- Although you can reconfigure versioning per-manager or per-datasource, it's unlikely that such a broad change would ever be needed
+- More commonly you would need to configure `versionScheme` for individual packages or potentially package patterns
+- The best way to do this is with `packageRules`, with a combination of `matchManagers`, `matchDatasources`, `matchPackageNames` and `matchPackagePatterns`
+
+## Examples of versioning overrides
+
+### Overriding Docker versioning to use a versioning specific for a package
+
+The configuration below overrides Renovate's default `docker` versioning for the `python` Docker image and instead uses the `pep440` versioning scheme to evaluate versions.
 
 ```json
 {
@@ -22,7 +38,18 @@ Configuring or overriding the default `versioning` can be helpful for ecosystems
 }
 ```
 
-The above will override Renovate's default of `docker` versioning for the `python` Docker image and instead use `pep440` versioning to evaluate versions.
+### Using a custom regex versioning scheme
+
+```json
+{
+  "packageRules": [
+    {
+      "matchPackageNames": ["foo/bar"],
+      "versionScheme": "regex:^(?<compatibility>.*)-v?(?<major>\\d+)\\.(?<minor>\\d+)\\.(?<patch>\\d+)?$"
+    }
+  ]
+}
+```
 
 ## Supported Versioning
 

lib/manager/ansible/readme.md

@@ -1 +1,3 @@
 Supports Docker-type dependency extraction from Ansible configuration files.
+
+If you need to change the versioning format, read the [versioning](https://docs.renovatebot.com/modules/versioning/) documentation to learn more.

lib/manager/bazel/readme.md

@@ -1 +1,5 @@
-Bazel is quite unlike most other "package managers" that Renovate supports, which usually focus on a particular ecosystem like JavaScript, Ruby or Docker. Instead, Bazel is a build tool so supports a multitude of languages/datasources. Renovate does not support all possible Bazel references, although would like to, and feature requests are welcome.
+Bazel is quite unlike most other "package managers" that Renovate supports, which usually focus on a particular ecosystem like JavaScript, Ruby or Docker.
+Instead, Bazel is a build tool so supports a multitude of languages/datasources.
+Renovate does not support all possible Bazel references, although would like to, and feature requests are welcome.
+
+If you need to change the versioning format, read the [versioning](https://docs.renovatebot.com/modules/versioning/) documentation to learn more.

lib/manager/buildkite/readme.md

@@ -1 +1,3 @@
 Used for updating Docker dependencies in Buildkite configuration files.
+
+If you need to change the versioning format, read the [versioning](https://docs.renovatebot.com/modules/versioning/) documentation to learn more.

lib/manager/circleci/readme.md

@@ -1 +1,3 @@
 The `circleci` manager extracts both `docker` as well as `orb` datasources from CircleCI config files.
+
+If you need to change the versioning format, read the [versioning](https://docs.renovatebot.com/modules/versioning/) documentation to learn more.

lib/manager/cloudbuild/readme.md

@@ -1 +1,3 @@
 The `cloudbuild` manager extracts `docker` datasources from [Cloud Build config files](https://cloud.google.com/build/docs/configuring-builds/create-basic-configuration).
+
+If you need to change the versioning format, read the [versioning](https://docs.renovatebot.com/modules/versioning/) documentation to learn more.

lib/manager/docker-compose/readme.md

@@ -1 +1,3 @@
 Extracts all Docker images from with Docker Compose YAML files.
+
+If you need to change the versioning format, read the [versioning](https://docs.renovatebot.com/modules/versioning/) documentation to learn more.

lib/manager/dockerfile/readme.md

@@ -1 +1,3 @@
 Extracts all Docker images in a `Dockerfile`.
+
+If you need to change the versioning format, read the [versioning](https://docs.renovatebot.com/modules/versioning/) documentation to learn more.

lib/manager/droneci/readme.md

@@ -1 +1,3 @@
 Extracts Docker-type dependencies from DroneCI config files.
+
+If you need to change the versioning format, read the [versioning](https://docs.renovatebot.com/modules/versioning/) documentation to learn more.

lib/manager/gitlabci/readme.md

@@ -1 +1,3 @@
 Extracts Docker dependencies from `gitlab-ci.yml` files.
+
+If you need to change the versioning format, read the [versioning](https://docs.renovatebot.com/modules/versioning/) documentation to learn more.

lib/manager/helm-requirements/readme.md

@@ -1,3 +1,5 @@
 Renovate supports updating Helm Chart references within `requirements.yaml` files.
 
 If your Helm charts make use of Aliases then you will need to configure an `aliases` object in your config to tell Renovate where to look for them.
+
+If you need to change the versioning format, read the [versioning](https://docs.renovatebot.com/modules/versioning/) documentation to learn more.

lib/manager/helm-values/readme.md

@@ -12,3 +12,5 @@ coreImage:
   repository: bitnami/harbor-core
   tag: 2.1.3-debian-10-r38
 ```
+
+If you need to change the versioning format, read the [versioning](https://docs.renovatebot.com/modules/versioning/) documentation to learn more.

lib/manager/helmfile/readme.md

@@ -1 +1,3 @@
 Checks `helmfile.yaml` files and extracts dependencies for the `helm` datasource.
+
+If you need to change the versioning format, read the [versioning](https://docs.renovatebot.com/modules/versioning/) documentation to learn more.

lib/manager/helmv3/readme.md

@@ -1,3 +1,5 @@
 Renovate supports updating Helm Chart references within `requirements.yaml` (Helm v2) and `Chart.yaml` (Helm v3) files.
 
 If your Helm charts make use of Aliases then you will need to configure an `aliases` object in your config to tell Renovate where to look for them.
+
+If you need to change the versioning format, read the [versioning](https://docs.renovatebot.com/modules/versioning/) documentation to learn more.

lib/manager/kubernetes/readme.md

@@ -29,3 +29,5 @@ Or if it's just a single file then something like this:
   }
 }
 ```
+
+If you need to change the versioning format, read the [versioning](https://docs.renovatebot.com/modules/versioning/) documentation to learn more.

lib/manager/terraform/readme.md

@@ -17,3 +17,5 @@ The following _range_ constraints are also supported:
 - `~> 1.2.0`: any non-beta version >= 1.2.0 and < 1.3.0, e.g. 1.2.X
 - `~> 1.2`: any non-beta version >= 1.2.0 and < 2.0.0, e.g. 1.X.Y
 - `>= 1.0.0`, <= 2.0.0`: any version between 1.0.0 and 2.0.0 inclusive
+
+If you need to change the versioning format, read the [versioning](https://docs.renovatebot.com/modules/versioning/) documentation to learn more.