fix #1001: document more version schemes + add examples

Author: RonnyPfannschmidt

CHANGELOG.md

@@ -19,6 +19,7 @@
 - fix #687: ensure calendar versioning tests use consistent time context to prevent failures around midnight in non-UTC timezones
 - reintroduce Python 3.9 entrypoints shim for compatibility
 - fix #1136: update customizing.md to fix missing import
+- fix #1001: document the missing version schemes and add examples in the docs
 
 ## v8.3.1
 

docs/extending.md

@@ -53,9 +53,41 @@ representing the version.
 `guess-next-dev (default)`
 :   Automatically guesses the next development version (default).
     Guesses the upcoming release by incrementing the pre-release segment if present,
-    otherwise by incrementing the micro segment. Then appends :code:`.devN`.
+    otherwise by incrementing the micro segment. Then appends `.devN`.
     In case the tag ends with `.dev0` the version is not bumped
-    and custom `.devN` versions will trigger a error.
+    and custom `.devN` versions will trigger an error.
+
+    **Examples:**
+    - Tag `1.0.0` → version `1.0.1.dev0` (if dirty or distance > 0)
+    - Tag `1.0.0` → version `1.0.0` (if exact match)
+
+`calver-by-date`
+:   Calendar versioning scheme that generates versions based on dates.
+    Uses the format `YY.MM.DD.patch` or `YYYY.MM.DD.patch` depending on the existing tag format.
+    If the commit is on the same date as the latest tag, increments the patch number.
+    Otherwise, uses the current date with patch 0. Supports branch-specific versioning
+    for release branches.
+
+    **Examples:**
+    - Tag `23.01.15.0` on same day → version `23.01.15.1.devN`
+    - Tag `23.01.15.0` on different day (e.g., 2023-01-16) → version `23.01.16.0.devN`
+    - Tag `2023.01.15.0` → uses 4-digit year format for new versions
+
+`no-guess-dev`
+:   Does no next version guessing, just adds `.post1.devN`.
+    This is the recommended replacement for the deprecated `post-release` scheme.
+
+    **Examples:**
+    - Tag `1.0.0` → version `1.0.0.post1.devN` (if distance > 0)
+    - Tag `1.0.0` → version `1.0.0` (if exact match)
+
+`only-version`
+:   Only use the version from the tag, as given.
+
+    !!! warning "This means version is no longer pseudo unique per commit"
+
+    **Examples:**
+    - Tag `1.0.0` → version `1.0.0` (always, regardless of distance or dirty state)
 
 `post-release (deprecated)`
 :   Generates post release versions (adds `.postN`)
@@ -64,6 +96,9 @@ representing the version.
 
     !!! warning "the recommended replacement is `no-guess-dev`"
 
+    **Examples:**
+    - Tag `1.0.0` → version `1.0.0.postN` (where N is the distance)
+
 `python-simplified-semver`
 :   Basic semantic versioning.
 
@@ -73,6 +108,10 @@ representing the version.
 
     This scheme is not compatible with pre-releases.
 
+    **Examples:**
+    - Tag `1.0.0` on non-feature branch → version `1.0.1.devN`
+    - Tag `1.0.0` on feature branch → version `1.1.0.devN`
+
 `release-branch-semver`
 :   Semantic versioning for projects with release branches.
     The same as `guess-next-dev` (incrementing the pre-release or micro segment)
@@ -81,14 +120,9 @@ representing the version.
     non-release branch, increments the minor segment and sets the micro segment to
     zero, then appends `.devN`
 
-`no-guess-dev`
-: Does no next version guessing, just adds `.post1.devN`
-
-`only-version`
-:   Only use the version from the tag, as given.
-
-    !!! warning "This means version is no longer pseudo unique per commit"
-
+    **Examples:**
+    - Tag `1.0.0` on release branch `release-1.0` → version `1.0.1.devN`
+    - Tag `1.0.0` on development branch → version `1.1.0.devN`
 
 ### `setuptools_scm.local_scheme`
 Configures how the local part of a version is rendered given a