From 20752c8118bdfad13808fb60dbe9f3b6063a170c Mon Sep 17 00:00:00 2001
From: HonkingGoose <34918129+HonkingGoose@users.noreply.github.com>
Date: Sat, 27 Mar 2021 06:50:57 +0100
Subject: [PATCH] docs: improve versioning documentation (#9017)

---
 docs/usage/modules/versioning.md        | 33 ++++++++++++++++++++++---
 lib/manager/ansible/readme.md           |  2 ++
 lib/manager/bazel/readme.md             |  6 ++++-
 lib/manager/buildkite/readme.md         |  2 ++
 lib/manager/circleci/readme.md          |  2 ++
 lib/manager/cloudbuild/readme.md        |  2 ++
 lib/manager/docker-compose/readme.md    |  2 ++
 lib/manager/dockerfile/readme.md        |  2 ++
 lib/manager/droneci/readme.md           |  2 ++
 lib/manager/gitlabci/readme.md          |  2 ++
 lib/manager/helm-requirements/readme.md |  2 ++
 lib/manager/helm-values/readme.md       |  2 ++
 lib/manager/helmfile/readme.md          |  2 ++
 lib/manager/helmv3/readme.md            |  2 ++
 lib/manager/kubernetes/readme.md        |  2 ++
 lib/manager/terraform/readme.md         |  2 ++
 16 files changed, 63 insertions(+), 4 deletions(-)

diff --git a/docs/usage/modules/versioning.md b/docs/usage/modules/versioning.md
index fb69749e3e..e5fcd8ef99 100644
--- a/docs/usage/modules/versioning.md
+++ b/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
 
diff --git a/lib/manager/ansible/readme.md b/lib/manager/ansible/readme.md
index 4b10e65c89..dbada08fb0 100644
--- a/lib/manager/ansible/readme.md
+++ b/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.
diff --git a/lib/manager/bazel/readme.md b/lib/manager/bazel/readme.md
index aef6f2e56e..8b0f06ce91 100644
--- a/lib/manager/bazel/readme.md
+++ b/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.
diff --git a/lib/manager/buildkite/readme.md b/lib/manager/buildkite/readme.md
index a5de9b3ae0..0c868a0912 100644
--- a/lib/manager/buildkite/readme.md
+++ b/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.
diff --git a/lib/manager/circleci/readme.md b/lib/manager/circleci/readme.md
index 6465259d70..39533ff501 100644
--- a/lib/manager/circleci/readme.md
+++ b/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.
diff --git a/lib/manager/cloudbuild/readme.md b/lib/manager/cloudbuild/readme.md
index b4f2845b19..c1c54fdb79 100644
--- a/lib/manager/cloudbuild/readme.md
+++ b/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.
diff --git a/lib/manager/docker-compose/readme.md b/lib/manager/docker-compose/readme.md
index 5f11e6ab92..389a5bb6fe 100644
--- a/lib/manager/docker-compose/readme.md
+++ b/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.
diff --git a/lib/manager/dockerfile/readme.md b/lib/manager/dockerfile/readme.md
index 0bd5e05073..81a83b76a0 100644
--- a/lib/manager/dockerfile/readme.md
+++ b/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.
diff --git a/lib/manager/droneci/readme.md b/lib/manager/droneci/readme.md
index d548370ddd..4c4f6b572d 100644
--- a/lib/manager/droneci/readme.md
+++ b/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.
diff --git a/lib/manager/gitlabci/readme.md b/lib/manager/gitlabci/readme.md
index 761a024dee..a40d170e7d 100644
--- a/lib/manager/gitlabci/readme.md
+++ b/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.
diff --git a/lib/manager/helm-requirements/readme.md b/lib/manager/helm-requirements/readme.md
index 38ba18ec41..bfe38755c5 100644
--- a/lib/manager/helm-requirements/readme.md
+++ b/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.
diff --git a/lib/manager/helm-values/readme.md b/lib/manager/helm-values/readme.md
index 815f1888f0..a604f2f0c8 100644
--- a/lib/manager/helm-values/readme.md
+++ b/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.
diff --git a/lib/manager/helmfile/readme.md b/lib/manager/helmfile/readme.md
index a77e0773d9..3dedb96283 100644
--- a/lib/manager/helmfile/readme.md
+++ b/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.
diff --git a/lib/manager/helmv3/readme.md b/lib/manager/helmv3/readme.md
index 7c0cd6e68b..c104f73092 100644
--- a/lib/manager/helmv3/readme.md
+++ b/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.
diff --git a/lib/manager/kubernetes/readme.md b/lib/manager/kubernetes/readme.md
index 75671a2668..a4ef3e7da2 100644
--- a/lib/manager/kubernetes/readme.md
+++ b/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.
diff --git a/lib/manager/terraform/readme.md b/lib/manager/terraform/readme.md
index 3d77a39080..4dd8321933 100644
--- a/lib/manager/terraform/readme.md
+++ b/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.
-- 
GitLab