docs: add RELEASING.md, bump workflow actions to Node 24 (#13)

* docs: add RELEASING.md, bump workflow actions to Node 24

docs/RELEASING.md captures the release flow as observed during the
v0.4.0-rc0 smoke test: prerequisites, the four version-bump locations,
the rc → final cycle with copy-pasteable commands, the workflow gate
table, common failure modes, and post-release verification. Mirrors
the forbin-mcp pattern but tailored to this project's TestPyPI staging
track.

Bump every pinned action to its latest major to clear the Node.js 20
deprecation warnings GitHub flagged on the v0.4.0-rc0 run:
  actions/checkout       v4 -> v6
  astral-sh/setup-uv     v4 -> v8
  actions/upload-artifact v4 -> v7
  actions/download-artifact v4 -> v8

Each major versioned independently per its maintainer's release cadence.
Node.js 20 is forced off runners in June 2026 and removed in September
2026; this gets us off well before then.

* ci: pin astral-sh/setup-uv to v8.1.0 (full version)

The previous bump used @v8 but astral-sh/setup-uv doesn't publish a
moving major tag — only full SemVer tags (v8.1.0, v8.0.0, etc.). The
test job failed with "Unable to resolve action astral-sh/setup-uv@v8,
unable to find version v8". Pinning to v8.1.0 (the latest released
tag) fixes resolution.

The other three actions (actions/checkout, upload-artifact,
download-artifact) all DO publish moving major tags, so @v6/@v7/@v8
remain valid for those.

* docs: address review feedback on RELEASING.md

- Drop "annotated" qualifier from the opener — every example uses a
  lightweight tag and tag-triggered workflows fire on either kind.
- Remove the stale Future work bullet about bumping action versions;
  the same PR already does that.

* chore: add uv-lock pre-commit hook

The RELEASING.md doc claimed pre-commit regenerates uv.lock when
pyproject.toml changes, but no hook was actually configured to do
that. The behavior worked incidentally because the pyright hook runs
`uv run`, which triggered uv to re-sync as a side effect.

Adding astral-sh/uv-pre-commit's uv-lock hook makes it explicit so
the docs claim is accurate and the lockfile sync no longer depends
on pyright happening to run uv first.

Author: chris-colinsky

.github/workflows/ci.yml

@@ -21,13 +21,13 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           # Conformance fixtures live in the openarmature-spec submodule.
           submodules: recursive
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v4
+        uses: astral-sh/setup-uv@v8.1.0
         with:
           enable-cache: true
 

.github/workflows/release.yml

@@ -23,13 +23,13 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           # Conformance fixtures live in the openarmature-spec submodule.
           submodules: recursive
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v4
+        uses: astral-sh/setup-uv@v8.1.0
         with:
           enable-cache: true
 
@@ -81,12 +81,12 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           submodules: recursive
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v4
+        uses: astral-sh/setup-uv@v8.1.0
         with:
           enable-cache: true
 
@@ -97,7 +97,7 @@ jobs:
         run: uv build
 
       - name: Upload dist artifact
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: dist
           path: dist/
@@ -114,7 +114,7 @@ jobs:
       id-token: write
     steps:
       - name: Download dist artifact
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v8
         with:
           name: dist
           path: dist/
@@ -140,7 +140,7 @@ jobs:
       id-token: write
     steps:
       - name: Download dist artifact
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v8
         with:
           name: dist
           path: dist/
@@ -159,10 +159,10 @@ jobs:
       contents: write
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Download dist artifact
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v8
         with:
           name: dist
           path: dist/

.pre-commit-config.yaml

@@ -16,6 +16,11 @@ repos:
         args: [--fix]
       - id: ruff-format
 
+  - repo: https://github.com/astral-sh/uv-pre-commit
+    rev: "0.11.10"
+    hooks:
+      - id: uv-lock
+
   - repo: local
     hooks:
       - id: pyright

docs/RELEASING.md

@@ -0,0 +1,176 @@
+# Releasing openarmature
+
+The release pipeline is tag-driven. Pushing a tag triggers
+`.github/workflows/release.yml`, which builds the package and either uploads
+to TestPyPI (pre-release tags) or PyPI plus a GitHub Release (final tags).
+
+## Prerequisites (one-time, already done)
+
+- Trusted Publisher pending entries on test.pypi.org and pypi.org for project
+  `openarmature`, owner `LunarCommand`, repo `openarmature-python`, workflow
+  `release.yml`. Environments: `testpypi` and `pypi`.
+- GitHub repo Environments: `testpypi` (no protection) and `pypi` (required
+  reviewer). The `pypi` reviewer protection is what makes the publish-pypi job
+  pause for a manual approval click on the Actions tab before any real-PyPI
+  upload — keep it on.
+
+## Where the version lives
+
+Four places stay in sync. A version bump touches all of them; pre-commit
+regenerates `uv.lock` automatically when you stage `pyproject.toml`.
+
+| File | Field | Notes |
+|---|---|---|
+| `pyproject.toml` | `[project] version` | Source of truth for the build |
+| `src/openarmature/__init__.py` | `__version__` | Read at import time |
+| `tests/test_smoke.py` | `assert __version__ == ...` | Drift guard |
+| `uv.lock` | `[[package]] openarmature version` | Regenerated by pre-commit |
+
+`__spec_version__` and `tool.openarmature.spec_version` are separate pins for
+the spec submodule; per the phased-rollout strategy, they're bumped only at
+release prep, not per-phase.
+
+## Release flow
+
+### 1. Bump to an RC version
+
+On main, in a small "release: prep" PR:
+
+```bash
+# Pick the version you intend to ship; suffix `rcN` for the first RC.
+vim pyproject.toml                    # version = "0.5.0rc1"
+vim src/openarmature/__init__.py      # __version__ = "0.5.0rc1"
+vim tests/test_smoke.py               # match
+# uv.lock auto-updates via pre-commit when you stage pyproject.toml
+git add pyproject.toml src/openarmature/__init__.py tests/test_smoke.py uv.lock
+git commit -m "release: prep 0.5.0-rc1"
+git push origin <branch>
+gh pr create --title "release: prep 0.5.0-rc1" ...
+```
+
+If this is the same release cycle as a previous RC, also bump the spec pins
+on the same PR if Phase 6's spec target requires it (`spec_version` in
+`pyproject.toml`, `__spec_version__` in `__init__.py`).
+
+Merge the PR.
+
+### 2. Tag the RC
+
+```bash
+git checkout main && git pull --ff-only
+git tag v0.5.0-rc1
+git push origin v0.5.0-rc1
+```
+
+The Release workflow fires. Job order: `test → build → publish-testpypi`.
+`publish-pypi` and `github-release` skip because the tag contains `-`.
+
+Watch the run: `gh run watch $(gh run list --workflow=release.yml --limit=1 --json databaseId --jq '.[0].databaseId') --exit-status`
+
+### 3. Verify the RC install
+
+In a fresh venv:
+
+```bash
+python3 -m venv /tmp/oa-verify
+/tmp/oa-verify/bin/pip install \
+    --index-url https://test.pypi.org/simple/ \
+    --extra-index-url https://pypi.org/simple/ \
+    openarmature==0.5.0rc1
+/tmp/oa-verify/bin/python -c "
+import openarmature
+from openarmature.graph import GraphBuilder, State, SubscribedObserver
+print(f'version: {openarmature.__version__}')
+print(f'spec_version: {openarmature.__spec_version__}')
+print('imports ok')
+"
+rm -rf /tmp/oa-verify
+```
+
+`--extra-index-url` is required: TestPyPI doesn't host all transitive deps
+(pydantic, etc.), so pip needs to fall back to real PyPI for them.
+
+If anything's wrong (broken install, wrong reported version, missing deps,
+README rendering issue on TestPyPI), fix on main and bump to `0.5.0rc2`. RC
+slots are one-shot — TestPyPI refuses re-uploads of the same version.
+
+### 4. Tag the real release
+
+When the RC verifies clean, drop the suffix on a new "release:" PR:
+
+```bash
+vim pyproject.toml                    # version = "0.5.0"
+vim src/openarmature/__init__.py      # __version__ = "0.5.0"
+vim tests/test_smoke.py               # match
+git add ...
+git commit -m "release: 0.5.0"
+gh pr create --title "release: 0.5.0" ...
+```
+
+Merge it. Then tag from main:
+
+```bash
+git checkout main && git pull --ff-only
+git tag v0.5.0
+git push origin v0.5.0
+```
+
+Job order: `test → build → publish-pypi → github-release`. The
+`publish-pypi` job pauses at the `pypi` environment with a "waiting for
+approval" notice. Click approve on the Actions tab; PyPI receives the
+upload; then `github-release` creates the public GitHub Release with
+auto-generated notes.
+
+## What the workflow gates on
+
+| Tag pattern | publish-testpypi | publish-pypi | github-release |
+|---|:---:|:---:|:---:|
+| `v0.5.0` | skip | run | run |
+| `v0.5.0-rc1`, `v0.5.0-rc2`, ... | run | skip | skip |
+| `v0.5.0-beta1`, `v0.5.0-alpha1`, ... | skip | skip | skip |
+
+The `-rc` suffix is the only pre-release form that actually publishes
+(to TestPyPI). Any other suffix is a no-op — failsafe against accidental
+uploads from misnamed tags. Real PyPI requires a clean SemVer tag with
+no suffix at all.
+
+The workflow also runs a "Verify pyproject.toml version matches tag"
+step before the build. PEP 440 normalization is applied via
+`packaging.version.Version`, so `0.5.0-rc1` ≡ `0.5.0rc1`.
+
+## Common failure modes
+
+**OIDC trust error on first publish.** The pending publisher on TestPyPI
+or PyPI hasn't been set up correctly. Re-check the four fields (project,
+owner, repo, workflow filename, environment) on the index's "Add a new
+pending publisher" form.
+
+**"version mismatch" failure in the test job.** `pyproject.toml` doesn't
+match the pushed tag after PEP 440 normalization. Fix `pyproject.toml`,
+make a new commit, and tag again with a fresh RC number — TestPyPI/PyPI
+won't accept a re-upload at the existing version.
+
+**publish-pypi never runs.** Check the tag name. Any `-` in the tag (rc,
+beta, alpha, dev) skips real-PyPI by design. Real release requires a
+clean `vX.Y.Z` tag with no suffix.
+
+**Approval gate stuck on `pypi` environment.** That's working as
+intended. Click "Review deployments" on the Actions run, approve the
+`pypi` environment.
+
+## Verifying after release
+
+- **PyPI**: https://pypi.org/project/openarmature/
+- **GitHub Release**: Releases tab on the repo; auto-generated notes
+  list every commit since the previous tag.
+- Smoke install in a fresh venv:
+  ```bash
+  pip install openarmature==<version>
+  python -c "import openarmature; print(openarmature.__version__)"
+  ```
+
+## Future work
+
+- A first-class `drain` deadline parameter (spec proposal in flight) will
+  change the engine API; release notes for that version should call it
+  out as a behavioral change.