Merge pull request #1165 from RonnyPfannschmidt/fix-docs-issues

documentation fixes - next round

Author: RonnyPfannschmidt

.github/workflows/python-tests.yml

@@ -51,6 +51,8 @@ jobs:
         with:
           python-version: ${{ matrix.python_version }}
           architecture: x64
+      - name: Install the latest version of uv
+        uses: astral-sh/setup-uv@v6
       - name: Setup MSYS2
         uses: msys2/setup-msys2@v2
         if: matrix.python_version == 'msys2'
@@ -81,20 +83,20 @@ jobs:
           echo "C:\Program Files (x86)\gnupg\bin" >> $env:GITHUB_PATH
           git config --system gpg.program "C:\Program Files (x86)\gnupg\bin\gpg.exe"
         if: runner.os == 'Windows'
-      - run: pip install -U 'setuptools>=61'
+      - run: uv sync --group test --group docs --extra rich
       - uses: actions/download-artifact@v4
         with:
           name: Packages
           path: dist
       - shell: bash
-        run: pip install "$(echo -n dist/*whl)[toml,test]"
+        run: uv pip install "$(echo -n dist/*whl)"
       - run: |
           $(hg debuginstall --template "{pythonexe}") -m pip install hg-git --user
         if: matrix.os == 'ubuntu-latest'
       # this hopefully helps with os caches, hg init sometimes gets 20s timeouts
       - run: hg version
-      - run: pytest
-        timeout-minutes: 15
+      - run: uv run pytest
+        timeout-minutes: 25
 
   dist_upload:
 

.readthedocs.yaml

@@ -1,16 +1,15 @@
 version: 2
-build:
-  os: ubuntu-22.04
-  tools:
-    python: "3.11"
 
 mkdocs:
   configuration: mkdocs.yml
 
-# Optionally declare the Python requirements required to build your docs
-python:
-  install:
-  - method: pip
-    path: .
-    extra_requirements:
-     - docs
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.13"
+  jobs:
+    install:
+      - pip install -U pip  # Official recommended way
+      - pip install .
+      - pip install --group docs

CHANGELOG.md

@@ -18,7 +18,7 @@
 - reduce complexity of HgWorkdir.get_meta method by extracting focused helper methods
 - fix #1150: enable setuptools-scm when we are a build requirement
 - feature #1154: add the commit id the the default version file template
-
+- drop scriv
 
 ### Fixed
 
@@ -36,6 +36,9 @@
 - fix #1100: add workaround for readthedocs worktress to the docs
 - fix #790: document shallow fail for rtd
 - fix #474: expand version not found error message to provide clearer guidance about SETUPTOOLS_SCM_PRETEND_VERSION_FOR_* environment variables
+- fix #324: document/recommend the v tag prefix
+- fix #501: add py.typed
+- fix #804: git - use fallback version instead of 0.0 when no version is found at all
 
 ## v8.3.1
 

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>),

hatch.toml

@@ -11,13 +11,9 @@ python = ["3.8", "3.9", "3.10", "3.11"]
 [envs.docs]
 python = "3.11"
 extras = ["docs"]
-dependencies = ["scriv"]
 
 [envs.docs.scripts]
 build = "mkdocs build --clean --strict"
 serve = "mkdocs serve --dev-addr localhost:8000"
 init = "mkdocs {args}"
-sync = ["entangled sync"]
-
-changelog-create = "scriv create {args}"
-changelog-collect = "scriv collect {args}"
+sync = ["entangled sync"]

pyproject.toml

@@ -48,6 +48,13 @@ dependencies = [
   'typing-extensions; python_version < "3.10"',
 ]
 [project.optional-dependencies]
+rich = [
+  "rich",
+]
+toml = [
+]
+
+[dependency-groups]
 docs = [
   #"entangled-cli~=2.0",
   "mkdocs",
@@ -57,21 +64,17 @@ docs = [
   "mkdocstrings[python]",
   "pygments",
 ]
-rich = [
-  "rich",
-]
 test = [
   "pip",
   "build",
   "pytest",
+  "pytest-timeout",  # Timeout protection for CI/CD
   "rich",
   'typing-extensions; python_version < "3.11"',
   "wheel",
   "griffe",
   "flake8",
 ]
-toml = [
-]
 
 [project.urls]
 documentation = "https://setuptools-scm.readthedocs.io/"
@@ -152,6 +155,7 @@ ignore = ["PP305", "GH103", "GH212", "MY100", "PC111", "PC160", "PC170", "PC180"
 [tool.pytest.ini_options]
 minversion = "8"
 testpaths = ["testing"]
+timeout = 300  # 5 minutes timeout per test for CI protection
 filterwarnings = [
   "error",
   "ignore:.*tool\\.setuptools_scm.*",
@@ -166,5 +170,5 @@ markers = [
   "skip_commit: allows to skip committing in the helpers",
 ]
 
-[tool.scriv]
-format = "md"
+[tool.uv]
+default-groups = ["test", "docs"]