| name | release |
| description | Cut a socratic-method release to GitHub Releases and PyPI. Use when asked to release, publish, tag a version, or ship vX.Y.Z of this package. Covers both the normal tag-push path and the dispatch fallback for environments whose git proxy cannot push tags (e.g. Claude Code remote sessions). |
Release socratic-method
Releases are tag-driven: an annotated tag vX.Y.Z on master fires
.github/workflows/release.yml, whose three jobs run in order: build + verify the
distributions, publish to PyPI via Trusted Publishing (OIDC; bound to workflow file
release.yml + environment pypi), then create the GitHub Release with the same
wheel and sdist attached. The GitHub Release is deliberately gated on the PyPI
publish — if PyPI fails, no release appears (PyPI is immutable, the release is not);
if only the github-release job fails, just re-run it.
Preconditions
- Master CI is green.
__version__ in src/socratic_method/__init__.py is bumped to X.Y.Z, in the literal
form __version__ = "X.Y.Z" — tag-release.yml parses that exact shape with sed.
This is the ONLY place the version lives (pyproject reads it dynamically).- The tag you will create is exactly
v + __version__; both workflows hard-fail on
mismatch.
- PyPI uploads are immutable: if a release went out broken, bump the patch version and
release again — never try to re-upload the same version.
Path A — normal (environment can push tags)
git tag -a vX.Y.Z -m "socratic-method X.Y.Z — <one-line summary>"
git push origin vX.Y.Z
The tag push triggers the Release workflow; skip to Verify.
Path B — dispatch fallback (tag pushes rejected, e.g. remote-session git proxy)
Symptom: git push origin vX.Y.Z fails with HTTP 403 while branch pushes succeed.
- Ensure master (with the version bump) is pushed.
- Dispatch the Tag release workflow (
tag-release.yml) on master with input
tag: vX.Y.Z. It verifies the tag matches __version__, then creates and pushes the
annotated tag server-side as github-actions[bot].
- Wait until the tag exists (
git ls-remote origin refs/tags/vX.Y.Z).
- Dispatch the Release workflow (
release.yml) with ref: vX.Y.Z — the TAG ref,
never a branch, or the tag/version check fails (GITHUB_REF_NAME must be the tag).
Both dispatches are always required on this path: tags created with the Actions
GITHUB_TOKEN do not fire tag-push events.
Verify (both paths)
- The Release run: all three jobs (
build, github-release, pypi) green.
- The GitHub Release
vX.Y.Z exists with BOTH assets attached:
socratic_method-X.Y.Z-py3-none-any.whl and socratic_method-X.Y.Z.tar.gz.
- PyPI shows the new version:
https://pypi.org/pypi/socratic-method/json lists both
files under urls.
- Optional end-to-end:
pip install --no-deps --target <tmpdir> socratic-method==X.Y.Z
and import it.
Do not report the release done until all of the above are confirmed.
