From 814cf29f478520e07ba07efc037c02dc48887b0d Mon Sep 17 00:00:00 2001
From: "dolgolyov.alexei" <dolgolyov.alexei@gmail.com>
Date: Tue, 7 Apr 2026 19:41:39 +0300
Subject: [PATCH] docs: add PEP 440 version normalization to section 3

Bare labels like 'dev' or 'nightly' break pip/setuptools when
stamped into pyproject.toml. Add a regex check that falls back
to 0.0.0.dev0 with a warning, plus a callout explaining the
gotcha.
---
 gitea-python-ci-cd.md | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/gitea-python-ci-cd.md b/gitea-python-ci-cd.md
index 51bf55a..54c34d5 100644
--- a/gitea-python-ci-cd.md
+++ b/gitea-python-ci-cd.md
@@ -240,8 +240,18 @@ if [ -z "$VERSION" ]; then
 fi
 
 VERSION_CLEAN="${VERSION#v}"  # Strip leading 'v'
+
+# Normalize non-PEP440 labels (e.g. "dev", "nightly", "snapshot") to a
+# valid PEP440 dev release. Without this, pip/setuptools rejects
+# pyproject.toml with: `project.version` must be pep440.
+if ! [[ "$VERSION_CLEAN" =~ ^[0-9]+(\.[0-9]+)*((a|b|rc|\.dev|\.post)[0-9]+)*(\+[a-zA-Z0-9.]+)?$ ]]; then
+    echo "  Warning: '$VERSION_CLEAN' is not PEP440-compliant, using 0.0.0.dev0"
+    VERSION_CLEAN="0.0.0.dev0"
+fi
 ```
 
+> **PEP 440 gotcha:** if a build script stamps a bare label like `dev` or `nightly` into `pyproject.toml`, the next `pip install` fails with `configuration error: project.version must be pep440`. Section 10.2 stamps the resolved version into `pyproject.toml`, so the version *must* be PEP 440-compliant before stamping. Valid forms: `1.2.3`, `1.2.3a1`, `1.2.3rc2`, `1.2.3.dev0`, `1.2.3.post1`, optionally with `+local` suffix. Invalid: `dev`, `vdev`, `nightly`, `snapshot-2024`. Always normalize before stamping.
+
 ## 4. Cross-Building Windows from Linux
 
 No Windows runner needed. Download Windows embedded Python and win_amd64 wheels on Linux.