Release-flow cleanup: version.py timing at tag, dead workflow references, stale RELEASE_MEMO, dead README-badge sed

[MilagrosMarin]

Four small release-automation inconsistencies surfaced during a v2.3.1 audit. Grouping them since they're all in the same "release-flow debris" bucket. Individually small; several are one-line fixes.

1. src/datajoint/version.py:4 — reports the previous release at every tag

At the v2.3.1 tag itself (commit 29ce695c), src/datajoint/version.py contains __version__ = "2.3.0". Same pattern at v2.3.0 (contains 2.2.4), v2.2.4, etc. — the bump PR always follows the tag.

Root cause: .github/workflows/post_draft_release_published.yaml sed's version.py and opens a bump PR after the release is published — so the tag is anchored on the pre-bump tree. PyPI is fine (Hatch builds the wheel from the sed'd file before twine upload in the same workflow run), but:

• pip install git+https://github.com/datajoint/datajoint-python.git@v2.3.1 → wheel with __version__ == "2.3.0".
• pip show datajoint on that install reports 2.3.0.
• Version-gated code (if datajoint.__version__ >= "2.3.1":) silently takes the wrong branch.

Options:

• (a) sed version.py before creating the tag (biggest change; requires reordering the release workflow).
• (b) Move the tag to the post-release bump commit (still requires workflow edit).
• (c) Switch to dynamic version resolution (hatch-vcs) so tag == reported version by construction (cleanest, biggest packaging change).

2. src/datajoint/version.py:1-2 — comment references workflow files that don't exist

# version bump auto managed by Github Actions:
# label_prs.yaml(prep), release.yaml(bump), post_release.yaml(edit)

None of label_prs.yaml, release.yaml, or post_release.yaml exist under .github/workflows/. The actual files that manage the release are draft_release.yaml and post_draft_release_published.yaml. Anyone tracing the release mechanism from this comment lands on missing files.

Fix: update the comment to name the actual workflows:

# version bump auto managed by Github Actions:
# draft_release.yaml (draft), post_draft_release_published.yaml (bump + PR)

3. RELEASE_MEMO.md:5-8 — branch structure table lists master as 2.1.x

| Branch     | Purpose             | Version |
|------------|---------------------|---------|
| `master`   | Main development    | 2.1.x   |    ← stale by two minor versions
| `maint/2.0`| Maintenance releases| 2.0.x   |

master currently ships 2.3.1. Since this is the authoritative-looking table under ## Branch Structure in a document explicitly titled "Release Memo", a new maintainer consulting it gets a two-minor-version-stale answer.

Fix: update master row to 2.3.x (or generalize the column to a rolling reference).

4. .github/workflows/post_draft_release_published.yaml:50-61 — dead "Update README.md badge" step

The step sed's id="commit-since-release-link" and id="commit-since-release-img" in README.md. Neither ID exists — the README was rewritten in commit ff04914c ("docs: Update README with Relational Workflow Model and OAS", 2026-01-04) and the "Since Release" row with those badge IDs was removed. grep -c commit-since-release README.md returns 0.

The step doesn't fail — the follow-up git diff --cached --quiet README.md || git commit guards the empty commit — but every release runs dead sed calls that produce no changes.

Fix options:

• (a) Remove the step (simplest — nobody's using the badge).
• (b) Re-add the badge markup to README and keep the step.

Suggested handling

• Finding 1 needs a maintainer decision — flagging, not proposing a specific fix.
• Findings 2, 3, 4 addressed in PR#1504.

[dimitri-yatsenko]

Decision needed on finding 1 (version.py timing). Because the version bump PR lands after the release tag, version.py at each tag still reports the previous version — so pip install git+https://github.com/datajoint/datajoint-python@v2.3.1 produces a wheel that reports 2.3.0, which breaks any version-gated code path.

Two ways to fix:

1. Reorder the release workflow so the bump commit is what gets tagged (tag follows the bump rather than preceding it).
2. Adopt hatch-vcs so the version is derived from the git tag at build time and there's no committed version to fall out of sync.

Findings 2–4 are already handled in PR #1504. Which direction do you want for finding 1?

[dimitri-yatsenko]

Progress: findings 2, 3, and 4 are resolved in merged #1504 (version.py comment now names the real workflows, RELEASE_MEMO.md branch table updated, dead README-badge sed step removed).

Only finding 1 (version.py reports the previous release at each tag) remains — it needs a maintainer decision; see the comment above for the two options.

[dimitri-yatsenko]

All four findings addressed and merged:

• Findings 2, 3, 4 (dead workflow comment in version.py, stale RELEASE_MEMO branch table, dead README-badge sed step) → chore(release-flow): stale doc pointers, RELEASE_MEMO cleanup, and dead badge step #1504.
• Finding 1 (version.py reports the previous release at each tag) → fix(release): derive version from git tag via hatch-vcs (#1503) #1507, which switches to hatch-vcs so the git tag is the single source of truth for pip install, pip show, and datajoint.__version__.

Closing.