From 64b219fd320670a427710a1a05289ce8a34c8aff Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?I=C3=B1igo=20Etxaniz?= <inigoetxaniz@gmail.com>
Date: Fri, 7 Aug 2026 16:09:51 +0000
Subject: [PATCH] templated project version

---
 .gitignore |  1 +
 README.md  | 27 +++++++++++++++++++++++++++
 2 files changed, 28 insertions(+)

diff --git a/.gitignore b/.gitignore
index 1a52355..7c97096 100644
--- a/.gitignore
+++ b/.gitignore
@@ -3,3 +3,4 @@ build/
 *.egg-info/
 __pycache__/
 *.pyc
+pyproject.toml
diff --git a/README.md b/README.md
index cc6a47e..1dd90d5 100644
--- a/README.md
+++ b/README.md
@@ -4,6 +4,33 @@ Python library for scripts running in an i7 job container. It gives a script thr
 plant signals (read and write) through the job's sidecar, the customer database through the
 db-controller, and millisecond time helpers.
 
+## Versioning and the pyproject template
+
+There is no `pyproject.toml` in this repository. It is generated from
+`pyproject.toml.tmpl`, and its version comes from the git tag that triggered the build:
+
+```toml
+version = "{{vless .TagName}}"
+```
+
+gitea-sidecar renders every `*.tmpl` file in the source to its name minus the suffix before
+building the wheel, so a tag of `v0.1.1` produces version `0.1.1` — `vless` strips the
+leading `v`, which git wants and PEP 440 does not. `.TagName` and `.CommitID` are also
+available for anything else worth stamping.
+
+The tag is therefore the only place a version is written. Do not add a hardcoded version
+back into the template: the build would keep producing that one version, and publishing a
+second tag would fail because the package file already exists.
+
+**Building locally** needs the same render step, since the file the build tools look for is
+not in the repository:
+
+```bash
+sed 's/{{vless .TagName}}/0.0.0.dev0/' pyproject.toml.tmpl > pyproject.toml
+```
+
+`pyproject.toml` is gitignored, so a local copy never reaches a build.
+
 ## Availability
 
 Inside a job container the library is already importable — the scheduler mounts the SDK