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:
@@ -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
|
||||
|
||||
@@ -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).
|
||||
|
||||
Reference in New Issue
Block a user