From 748c9d18f9059a3b599626702458c083274e6ad9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?I=C3=B1igo=20Etxaniz?= <inigoetxaniz@gmail.com>
Date: Fri, 7 Aug 2026 18:24:28 +0200
Subject: [PATCH] move the versioning section below the library reference

---
 README.md | 48 ++++++++++++++++++++++--------------------------
 1 file changed, 22 insertions(+), 26 deletions(-)

diff --git a/README.md b/README.md
index 9628ae8..0c82002 100644
--- a/README.md
+++ b/README.md
@@ -4,32 +4,6 @@ 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.
-
-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
@@ -150,6 +124,28 @@ fast `interval_ms` loop.
 
 **`to_datetime(unix_milli)`** — converts back to a local `datetime`, for logging.
 
+## Versioning and the pyproject template
+
+There is no `pyproject.toml` in this repository — it is generated from
+`pyproject.toml.tmpl`, whose version line reads `version = "{{vless .TagName}}"`.
+gitea-sidecar renders every `*.tmpl` in the source to its name minus the suffix before
+building the wheel, so a tag of `v0.1.3` publishes version `0.1.3`; `vless` strips the
+leading `v` that git wants and PEP 440 forbids. The tag is the only place a version is
+written, and the published wheel cannot disagree with the tag that produced it.
+
+Do not put a hardcoded version back into the template: the build would keep producing that
+one version, and the next tag would fail with a 409 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.
+
 ## Error handling
 
 Every method in this library catches its own exceptions, prints a line, and returns an empty