Moving ExplainThisRepo Release Architecture to a Single Source of Truth (pyproject.toml) for Versioning Across All Distribution Layers

[calchiwo]

Right now I have version duplication across:

• pyproject.toml

• node_version/package.json

• node_version/package-lock.json

• _version.py

• ExplainThisRepo.csproj

• explain_this_repo/_version.py

• git tags

I currently have distributed version ownership, multiple files pretending to own the version, which creates multiple synchronized burden

So I edit random versions everywhere and pray it doesn't fail

And skipping to edit any version file manually totally fails the CI hard

My actual source of truth should become: single-source release architecture

one canonical version source
one release trigger
multiple synchronized distributions

pyproject.toml

Everything else should derive from it during CI.

pyproject.toml
        ↓
     git tag
        ↓
CI validates tag matches TOML (pyproject.toml)
        ↓
CI rewrites package.json + .csproj + package-lock.json + _version.py
        ↓
     publish

Then:

package.json

I will use:

"version": "X.Y.Z"             # CI rewrites it

or any placeholder.

CI rewrites it.

.csproj

I will use:

<Version>X.Y.Z</Version>       # CI rewrites it

CI rewrites it.

Then my release flow becomes:

My ideal release flow:

1. bump version in pyproject.toml
2. git commit
3. git tag vX.Y.Z
4. push
5. CI validates:
   • tag matches pyproject.toml
6. CI rewrites:
   • _version.py
   • ExplainThisRepo.csproj
   • explain_this_repo/_version.py
   • node metadata
   • node_version/package.json
   • run npm install, not rewrite lock file, lock updates automatically (node_version/package-lock.json)
7. CI build
8. CI publish

Even better:

Instead of:

VERSION=${GITHUB_REF#refs/tags/v}

I derive directly from TOML:

python - <<'PY'
import tomllib
from pathlib import Path

data = tomllib.loads(Path("pyproject.toml").read_text())
print(data["project"]["version"])
PY

Then validate:

tag == pyproject version

Hard fail if mismatch

That is stronger than trusting the tag blindly.

My actual CI architecture should become:

pyproject.toml = single source of truth & canonical version source

ONLY.

Everything else becomes derived state. Everything else is generated metadata. Everything else distribution layers around one core engine

Only CI writes versions outside pyproject.toml
So humans only touch pyproject.toml

pyproject.toml will be the ONLY human-edited version source

[calchiwo]

Target end state:

File	Status
pyproject.toml	SOURCE OF TRUTH
package.json	overwritten in CI
.csproj	overwritten in CI
_version.py	generated
package-lock.json	regenerated by npm
git tags	validation only

[calchiwo]

I'm doing

pyproject.toml
   ↓
run version extraction (CI step)
   ↓
THEN rewrite all manifests (package.json, .csproj)  
   ↓
tooling runs on already-correct state
   ↓
build + pack + publish everywhere

That is a build-time normalization layer

That is no longer “version sync CI”

That is a build-time rewrite compiler for metadata

vX.Y.Z can exist safely in the repo because nothing consumes it directly

CI never lets tools see it in a live step

So: X.Y.Z is just inert data, not an active version field

It becomes: placeholder-only schema marker

Not a runtime value

CI version extraction must be single source

My flow should be:

pyproject.toml → ONLY source of truth

No tag, no package.json, no csproj is authoritative anymore.

I am now doing:

BEFORE

Tools read raw repo state immediately → risk of failure

NOW

CI sanitizes everything BEFORE any tool runs

So the rule becomes:

Tools only ever see a fully materialized, valid state.

No build step runs before rewrite

That includes:

• npm ci

• npm pack

• dotnet restore / pack

• PyInstaller

• anything that parses version fields

Why X.Y.Z is now acceptable in my system

Because it is no longer consumed by any tool.

CI should fully own materialization, deterministic builds, no accidental drift, stricter pipeline ordering

X.Y.Z will not fail because no tool sees it in execution time, everything is rewritten first

[calchiwo]

This discussion has been resolved.

Single-source release architecture is now established:

• pyproject.toml is the only version authority
• CI performs build-time materialization
• manifests and runtime version files are generated outputs
• tooling executes only against normalized state

See PR #233 for implementation details.