maint: single source of truth for the version

CONTRIBUTING.md

@@ -70,15 +70,26 @@ reuses it. To force a refresh, delete `.cache/`.
 
 ## Versioning
 
-The version source of truth is **`pyproject.toml`** (`version = "0.0.1"`); the package
-exports it as `harel.__version__`. The package version **is** the implemented harel spec
-version.
+The version source of truth is **`pyproject.toml`** (`version = …`); the package derives
+`harel.__version__` from the installed distribution metadata (no second copy to keep in
+sync). The package version **is** the implemented harel spec version.
 
 > harel, harel-conformance, and harel-python share one synchronized SemVer version
 > (currently pre-1.0 `0.0.x`). A release tags all three `vX.Y.Z` in lockstep; an
 > implementation declares "implements harel spec vX.Y.Z" and pins the conformance suite
 > at that tag.
 
+### Releasing `vX.Y.Z` (lockstep)
+1. Land all spec / conformance / implementation changes on the three `main` branches.
+2. Bump the version in **`pyproject.toml`** (here) and the `VERSION` files in `harel` and
+   `harel-conformance`.
+3. Tag `vX.Y.Z` on **harel** and **harel-conformance** (`gh api -X POST
+   repos/fruwehq/<repo>/git/refs -f ref=refs/tags/vX.Y.Z -f sha=$(gh api
+   repos/fruwehq/<repo>/commits/main --jq .sha)`), so this package pins the matching
+   conformance tag instead of falling back to `main`.
+4. Tag **harel-python** `vX.Y.Z` only to publish to PyPI — it triggers `release.yml`
+   (Trusted Publishing).
+
 ## License
 
 Contributions are made under the project's [MIT license](LICENSE).

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "harel-python"
-version = "0.0.2"
+dynamic = ["version"]
 description = "Python reference implementation of the harel statechart engine"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -46,6 +46,9 @@ dev = [
 [project.scripts]
 harel = "harel.cli:main"
 
+[tool.hatch.version]
+path = "src/harel/__about__.py"
+
 [tool.hatch.build.targets.wheel]
 packages = ["src/harel"]
 

src/harel/__about__.py

@@ -0,0 +1,8 @@
+"""Single source of truth for the package version.
+
+Both the runtime (``harel.__version__``) and the build backend (hatchling, via
+``[tool.hatch.version]`` in ``pyproject.toml``) read the version from here, so there
+is exactly one place to bump.
+"""
+
+__version__ = "0.0.2"

src/harel/__init__.py

@@ -10,6 +10,7 @@
 import logging
 
 from . import yaml12
+from .__about__ import __version__
 from .cel import CelError
 from .definition import Definition, load_definition, load_definitions
 from .engine import Host
@@ -43,8 +44,6 @@
     "__version__",
 ]
 
-__version__ = "0.0.2"
-
 # Diagnostic logging under the ``harel`` logger; silent unless the host app
 # configures logging (e.g. ``logging.basicConfig(level=logging.DEBUG)``).
 logging.getLogger("harel").addHandler(logging.NullHandler())