keep the checked-in version bumped in step with releases

[espg]

Closes #9. Follow-up to #8 (merged as e6f2e99), which made the release tag the source of the published version.

The drift is live right now

0.3.2 is released, built through #8's tag-driven path — and main's Cargo.toml still says 0.3.1. So every from-source install off main today reports a version that was superseded:

$ git show origin/main:Cargo.toml | grep -m1 '^version'
version = "0.3.1"

That is exactly the state #9 exists to correct, so part (1) is a correction of the current tree rather than a hypothetical.

Phases

• 1 — Correct the drift. Bump the checked-in version to 0.3.2.
• 2 — Document the convention. A ## Releasing section in the README.
• 3 — Warn-only tag-vs-tree check. ::warning:: on a release run when the two disagree; never fails the job.

1. Bump to 0.3.2 (5ab15d6)

Cargo.toml and the crate's own [[package]] entry in Cargo.lock — the lock is load-bearing because the wheel builds pass --locked, so bumping only the manifest is a hard build failure, not a cosmetic mismatch. Done by running #8's own sync-version.sh 0.3.2 rather than hand-editing, so the rewrite is the same awk-scoped pass CI performs. Exactly two lines change and no dependency version is touched:

$ .github/scripts/sync-version.sh 0.3.2
version synced to 0.3.2
version = "0.3.2"
$ git diff --stat
 Cargo.lock | 2 +-
 Cargo.toml | 2 +-
$ cargo metadata --locked --offline --format-version 1 --no-deps \
    | python3 -c 'import json,sys; print([(p["name"],p["version"]) for p in json.load(sys.stdin)["packages"]])'
[('h5coro-hidefix', '0.3.2')]    # exit=0 -- the lockfile is still valid under --locked

2. ## Releasing in the README (7a1e6e1)

The repo has no RELEASING.md, CONTRIBUTING.md, or changelog, and the README already carries the operational prose (## Development covers the local build, the test tiers, and what CI builds), so the section goes there, immediately after ## Development, rather than introducing a new file for ~30 lines.

It states the three things the issue asks for: a bump version to X commit lands on main for each release; the tag is what the build reads (so a forgotten bump cannot mislabel a wheel); and from-source installs — pip install git+…, a local pip install . / maturin develop, any cargo consumer of a checkout — read the tree and never see the tag, which is why the two must not drift. The concrete recipe it documents is the one used in phase 1 above (sync-version.sh X → cargo metadata --locked --offline → bump commit → tag).

3. Warn-only check (339776a)

.github/scripts/check-tree-version.sh, following #8's script structure rather than inline YAML (same release-version.sh default-argument shape, same [version] [manifest] override for local testing, same annotation vocabulary), wired into publish:

      - name: Warn if the checked-in version lags the tag
        run: .github/scripts/check-tree-version.sh

Two deliberate choices:

• Placed in publish, after the artifact-name check. That job's checkout is the only one in the workflow that is never version-synced, so its Cargo.toml is exactly what the tagged commit hands to a from-source install — the thing being checked. It also fires once per release rather than four times, and the warning is a post-release to-do (land the bump commit), not something actionable mid-run.
• set -uo pipefail, deliberately not -e, unlike its three siblings, with the reason stated in the header comment. Every path exits 0, including "cannot determine the tag version" and "manifest unreadable". release-version.sh's stderr is swallowed on that fallback path specifically because it speaks in ::error:: annotations, and nothing in a warn-only check should annotate a run as failed.

Verification

No release run was available and no tag was touched, so the check was exercised directly against real trees, replaying what the publish job's checkout would contain.

Disagreement — origin/main's tree (0.3.1) against tag 0.3.2, i.e. today's actual state:

$ git archive origin/main | tar -x -C /tmp/main && cd /tmp/main
$ cp $BRANCH/.github/scripts/check-tree-version.sh .github/scripts/   # not on main yet
$ GITHUB_REF=refs/tags/0.3.2 .github/scripts/check-tree-version.sh
::warning::release tag is 0.3.2 but the checked-in Cargo.toml says 0.3.1. The published artifacts carry 0.3.2 (the build syncs them), but installs built from the tree -- pip install git+..., a local pip install ., cargo consumers -- will report 0.3.1. Land a 'bump version to 0.3.2' commit on main.
exit=0

Agreement — this branch's tree (0.3.2) against tag 0.3.2:

$ git archive HEAD | tar -x -C /tmp/br && cd /tmp/br
$ GITHUB_REF=refs/tags/0.3.2 .github/scripts/check-tree-version.sh
checked-in version matches the release tag (0.3.2)
exit=0

Degenerate inputs, all warn-and-continue (no ::error::, exit 0):

$ GITHUB_REF=refs/heads/main .github/scripts/check-tree-version.sh
::warning::could not determine the release version from the tag; skipping the tag-vs-tree version check.
exit=0
$ .github/scripts/check-tree-version.sh 0.3.2 /tmp/nope.toml
::warning::'/tmp/nope.toml' is not readable; skipping the tag-vs-tree version check.
exit=0
$ .github/scripts/check-tree-version.sh 0.3.2 /tmp/noversion.toml   # version line deleted
::warning::no [package] version found in '/tmp/noversion.toml'; skipping the tag-vs-tree version check.
exit=0

Repo gates (the local equivalents of ci.yml; there is no pre-commit config, and no shellcheck/actionlint/yamllint is configured or installed):

$ cargo fmt --check                                  exit=0
$ cargo clippy --locked -- -D warnings                exit=0
$ cargo metadata --locked --offline                   exit=0
$ pytest tests/test_hermetic.py -q                    41 passed in 0.28s
$ bash -n .github/scripts/*.sh                        all ok
$ python -c "yaml.safe_load(open('.github/workflows/wheels.yml'))"   parses

Not verified: the step firing inside a real publish job — the first exercise is the next tag push. Its only inputs are GITHUB_REF and the checked-out Cargo.toml, both replayed above.

Questions for review

1. After this merges, 0.3.2 is released but its tag points at a commit whose tree still says 0.3.1. Nothing needs re-releasing (the published artifacts are correctly named 0.3.2 — the tag-driven build saw to that), and the bump commit here makes every future from-source install off main honest. The alternative is moving the 0.3.2 tag onto the merged head so the tag and its tree agree retroactively; that is a tag rewrite, so it is yours to make if wanted, not something done here. Leaving it as-is seems right — preference?
2. Warning placement. publish was chosen for the reasons above, which means a release whose build jobs fail never emits the warning. That seemed correct (a run that publishes nothing does not need the nag), but if you would rather see it early and unconditionally, it moves to a standalone tag-gated job or to a pre-sync step in sdist.

[espg]

🤖 from Claude

CI green on 339776a — run 31575551911: test (ubuntu-latest) and test (macos-14) both succeeded (cargo fmt --check, cargo clippy --locked -- -D warnings, pip install -v ".[test]", pytest tests/test_hermetic.py).

Note that PR CI cannot exercise the new step itself: wheels.yml triggers only on pushes to main and on tags, so check-tree-version.sh first runs on the next tag push. The replays in the PR body stand in for it — they feed the script the same two inputs the publish job would (GITHUB_REF and a fresh checkout's Cargo.toml).

Left as a draft: the two items under "Questions for review" are yours to rule on — in particular whether the released 0.3.2 tag should be left pointing at a 0.3.1 tree, or moved onto the merged head.