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 <vibe@mistral.ai>
This commit is contained in:
nvaldez
2026-11-19 11:12:58 +01:00
parent 64373b7b1a
commit 0e4fe45bc1
2 changed files with 63 additions and 2 deletions
+10
View File
@@ -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<x.y.z> -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
+53 -2
View File
@@ -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)
<!-- toc-end -->
@@ -70,11 +71,15 @@ phronesis/
├── test/ # pytest suite, one module per source module
├── skill/ # One directory per skill; ships as package data
│ └── <name>/
│ └── SKILL.md
│ ├── SKILL.md # required front matter file
│ └── <support files> # 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<version>` 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<version>` 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/<name>-<version>.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/<v>/...`),
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<version>` 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).