fix #324: document/recommend the v prefix

Author: RonnyPfannschmidt

docs/config.md

@@ -67,6 +67,14 @@ Callables or other Python objects have to be passed in `setup.py` (via the `use_
     named `version`, that captures the actual version information.
 
     Defaults to the value of [setuptools_scm._config.DEFAULT_TAG_REGEX][]
+    which supports tags with optional "v" prefix (recommended), project prefixes,
+    and various version formats.
+
+    !!! tip
+
+        The default regex supports common tag formats like `v1.0.0`, `myproject-v1.0.0`,
+        and `1.0.0`. For best practices on tag naming, see
+        [Version Tag Formats](usage.md#version-tag-formats).
 
 `parentdir_prefix_version: str|None = None`
 :   If the normal methods for detecting the version (SCM version,

docs/extending.md

@@ -58,8 +58,8 @@ representing the version.
     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)
+    - Tag `v1.0.0` → version `1.0.1.dev0` (if dirty or distance > 0)
+    - Tag `v1.0.0` → version `1.0.0` (if exact match)
 
 `calver-by-date`
 :   Calendar versioning scheme that generates versions based on dates.
@@ -69,25 +69,25 @@ representing the version.
     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
+    - Tag `v23.01.15.0` on same day → version `23.01.15.1.devN`
+    - Tag `v23.01.15.0` on different day (e.g., 2023-01-16) → version `23.01.16.0.devN`
+    - Tag `v2023.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)
+    - Tag `v1.0.0` → version `1.0.0.post1.devN` (if distance > 0)
+    - Tag `v1.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)
+    - Tag `v1.0.0` → version `1.0.0` (always, regardless of distance or dirty state)
 
 `post-release (deprecated)`
 :   Generates post release versions (adds `.postN`)

docs/index.md

@@ -43,8 +43,21 @@ dynamic = ["version"]
 # more missing
 
 [tool.setuptools_scm]
+´´´
 
-```
+
+!!! tip "Recommended Tag Format"
+
+    Use the **"v" prefix** for your version tags for best compatibility:
+
+    ```bash
+    git tag v1.0.0
+    git tag v1.1.0
+    git tag v2.0.0-rc1
+    ```
+
+    This is a widely adopted convention that works well with setuptools-scm and other tools.
+    See the [Version Tag Formats](usage.md#version-tag-formats) section for more details.
 
 
 ### With hatch

docs/overrides.md

@@ -50,6 +50,15 @@ Use with a specific package:
 export SETUPTOOLS_SCM_PRETEND_METADATA_FOR_MY_PACKAGE='{node="g1234567", distance=2}'
 ```
 
+!!! note "Node ID Prefixes"
+
+    Node IDs must include the appropriate SCM prefix:
+
+    - Use `g` prefix for git repositories (e.g., `g1a2b3c4d5`)
+    - Use `h` prefix for mercurial repositories (e.g., `h1a2b3c4d5`)
+
+    This ensures consistency with setuptools-scm's automatic node ID formatting.
+
 ### Use case: CI/CD environments
 
 This is particularly useful for solving issues where version file templates need access to

docs/usage.md

@@ -253,6 +253,100 @@ For Git projects, the version relies on  [git describe](https://git-scm.com/docs
 so you will see an additional `g` prepended to the `{revision hash}`.
 
 
+## Version Tag Formats
+
+setuptools-scm automatically detects version information from SCM tags. The default tag regex
+supports a wide variety of tag formats, with the **"v" prefix being recommended** for clarity
+and consistency.
+
+### Recommended Tag Format
+
+**Use the "v" prefix for version tags:**
+
+```bash
+git tag v1.0.0        # Recommended
+git tag v2.1.3
+git tag v1.0.0-alpha1
+git tag v1.0.0-rc1
+```
+
+### Supported Tag Formats
+
+setuptools-scm's default tag regex supports:
+
+- **Version prefix**: `v` or `V` (optional, but recommended)
+- **Project prefix**: Optional project name followed by dashes (e.g., `myproject-v1.0.0`)
+- **Version number**: Standard semantic versioning patterns
+- **Pre-release suffixes**: Alpha, beta, RC versions
+- **Build metadata**: Anything after `+` is ignored
+
+**Examples of valid tags:**
+```bash
+# Recommended formats (with v prefix)
+v1.0.0
+v2.1.3
+v1.0.0-alpha1
+v1.0.0-beta2
+v1.0.0-rc1
+v1.2.3-dev
+V1.0.0              # Capital V also works
+
+# Project-prefixed formats
+myproject-v1.0.0
+my-lib-v2.1.0
+
+# Without v prefix (supported but not recommended)
+1.0.0
+2.1.3
+1.0.0-alpha1
+
+# With build metadata (metadata after + is ignored)
+v1.0.0+build.123
+v1.0.0+20240115
+```
+
+### Why Use the "v" Prefix?
+
+1. **Clarity**: Makes it immediately obvious that the tag represents a version
+2. **Convention**: Widely adopted standard across the software industry
+3. **Git compatibility**: Works well with git's tag sorting and filtering
+4. **Tool compatibility**: Many other tools expect version tags to have a "v" prefix
+
+### Custom Tag Patterns
+
+If you need different tag patterns, you can customize the tag regex:
+
+```toml title="pyproject.toml"
+[tool.setuptools_scm]
+tag_regex = "^release-(?P<version>[0-9]+\\.[0-9]+\\.[0-9]+)$"
+```
+
+## Node ID Prefixes
+
+setuptools-scm automatically prepends identifying characters to node IDs (commit/revision hashes)
+to distinguish between different SCM systems:
+
+- **Git repositories**: Node IDs are prefixed with `g` (e.g., `g1a2b3c4d5`)
+- **Mercurial repositories**: Node IDs are prefixed with `h` (e.g., `h1a2b3c4d5`)
+
+This prefixing serves several purposes:
+
+1. **SCM identification**: Makes it clear which version control system was used
+2. **Consistency**: Ensures predictable node ID format across different SCM backends
+3. **Debugging**: Helps identify the source SCM when troubleshooting version issues
+
+The prefixes are automatically added by setuptools-scm and should be included when manually
+specifying node IDs in environment variables like `SETUPTOOLS_SCM_PRETEND_METADATA`.
+
+**Examples:**
+```bash
+# Git node ID
+1.0.0.dev5+g1a2b3c4d5
+
+# Mercurial node ID
+1.0.0.dev5+h1a2b3c4d5
+```
+
 !!! note
 
     According to [PEP 440](https://peps.python.org/pep-0440/#local-version-identifiers>),