From 0e4fe45bc10b6ea27731647156d6a6f9e257ea96 Mon Sep 17 00:00:00 2001 From: nvaldez Date: Thu, 19 Nov 2026 11:12:58 +0100 Subject: [PATCH] docs: SPEC.md section 12 Release + layout sync - spec current with the repo Audit found the spec accurate through the skills port but silent on the release tooling. Added section 12 (publish.py guards and exit codes, roller-tag tolerance, immutable published versions, absolute-link README rule found at 0.1.0, MANIFEST.in and dist/ policy) and refreshed the item 2.1 tree (publish.py, MANIFEST.in, dist/, skill support files). CONTRIBUTING gains a short Releasing section pointing at SPEC 12. Generated by Mistral Vibe. Co-Authored-By: Mistral Vibe --- CONTRIBUTING.md | 10 +++++++++ SPEC.md | 55 +++++++++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 63 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b647e59..750f7bb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -62,6 +62,16 @@ reading only that file should be able to follow the skill. - Plain, imperative sentences. Lists over prose where order matters. - Test what you preach: a TDD skill is itself written cleanly. +## Releasing + +- Bump `version` in `pyproject.toml`, commit, then tag the release: + `git tag -a v -m "..."` and move the `stable`/`latest` + roller tags (`git tag -f ...`, `git push -f origin stable latest`). +- `python publish.py` guards, builds, and twine-checks exactly the + tagged version; `python publish.py --upload` publishes it + ([SPEC.md section 12](./SPEC.md)). A published version is + immutable: any change, even to the README, is a new version. + ## License By contributing you agree your work is released under the diff --git a/SPEC.md b/SPEC.md index cc1aa0e..71f74fa 100644 --- a/SPEC.md +++ b/SPEC.md @@ -18,6 +18,7 @@ behavior changes, then change the code and the tests to match. - [9. Quality gates](#9-quality-gates) - [10. Packaging](#10-packaging) - [11. Implementation plan](#11-implementation-plan) +- [12. Release](#12-release) @@ -70,11 +71,15 @@ phronesis/ ├── test/ # pytest suite, one module per source module ├── skill/ # One directory per skill; ships as package data │ └── / -│ └── SKILL.md +│ ├── SKILL.md # required front matter file +│ └── # templates, rules, scripts (optional; all ship) +├── publish.py # Release guards, build, twine check/upload (section 12) +├── MANIFEST.in # Ships skill/ in the sdist ├── autotest.py # Every repo check, single entry point ├── SPEC.md # This file ├── README.md, CONTRIBUTING.md, LICENSE -└── pyproject.toml, requirements.txt +├── pyproject.toml, requirements.txt +└── dist/ # Build artifacts, gitignored ``` - **2.2** The skills ship through the package as @@ -304,3 +309,49 @@ python-tdd 1.2.0 development the parts above; end to end tests through `main(argv)`. - **11.6** The implementation order is bottom up so every layer has a test before its consumer exists. + +## 12. Release + +- **12.1** `publish.py` at the repository root releases the package to + PyPI, ported from daedalus `python/src/publish/publish.py`: guards, + a chained sdist to wheel build, `twine check`, and with `--upload` + a twine upload of exactly this version's two artifacts. It is run + from the checkout (`.venv/bin/python publish.py [--upload]`); the + state of the tree is the source of truth. +- **12.2** Guards, each stopping before anything is built: no + `pyproject.toml` beside the script is exit 2; a dirty working tree + is exit 3; a HEAD whose tags do not include `v` is exit 4 + with the tags it actually carries printed; missing + `python -m build` or `python -m twine` is exit 5 with the + `pipx inject phronesis build twine` hint; a version already on PyPI, + or a PyPI that cannot be reached, is exit 6 (never publish blind). +- **12.3** The tag guard lists the tags on HEAD and accepts + `v` among them, so the `stable` and `latest` roller tags + on the same commit never trip it. +- **12.4** Build failure is exit 7; a `twine check` complaint (for + example a README that will not render) is exit 8. Without + `--upload` the run ends there with exit 0 and prints the command + that would upload. +- **12.5** `--upload` runs `python -m twine upload` over exactly + `dist/-.tar.gz` and the matching wheel, never + `dist/*`: upload failure is exit 9. Credentials are never handled + by the script: twine prompts or reads `~/.pypirc` (username + `__token__` with a PyPI API token). +- **12.6** A published version is immutable (guard item 12.2, exit 6). + To change anything, including the README that PyPI renders, bump + the version in `pyproject.toml`, commit, tag, and release again + (daedalus SPEC item 9.8 practice). +- **12.7** The README that ships must use absolute links to the + repository web UI: PyPI resolves relative links against the + project page and they break (`pypi.org/project/phronesis//...`), + found at 0.1.0. Links target `src/branch/master` on the repository + server; markdown anchors (`#...`) stay relative and keep working. +- **12.8** `MANIFEST.in` ships `skill/` in the sdist; the wheel + carries the skills as `phronesis._skills` package data (SPEC item + 10.3); `dist/` is build output, gitignored, and never committed. +- **12.9** Release tags: `v` on the release commit, and the + `stable` and `latest` roller tags moved onto the same commit + (`git tag -f ...` plus `git push -f origin stable latest`). +- **12.10** Release tooling dependencies (`build`, `twine`) live in + `requirements.txt` (SPEC item 9.5); the wheel's runtime + dependencies stay minimal (SPEC item 10.2).