From cfbb66ce39ee3ca86a7f77cbe216e651e5ca7427 Mon Sep 17 00:00:00 2001 From: nvaldez Date: Thu, 19 Nov 2026 11:10:28 +0100 Subject: [PATCH] docs: SPEC refresh - drop template wording, add release contract (9.9), PyPI install rows Audit against the live repo after 0.11.0-0.13.1: - preamble, item 1.2, and section 4 no longer claim "empty template" (five scripts registered; the registry is the truth) - item 2.1 tree: MANIFEST.in shown, requirements.txt comment says test/lint/release tools - item 9.1 install table: pipx install daedalus-tools from PyPI and pipx upgrade daedalus-tools rows; public Gitea URL - new item 9.9 Releasing: version bump, changelog, annotated v tag, latest follows, stable pinned, daedalus publish as the guarded one-command flow (cites the publish spec; a published version is immutable by design) - items 7.11 and 9.6 include the build/twine release tooling SPEC.md ships in the repo only (never in sdist/wheel), so no version bump; docs-only commit on main after the v0.13.1 tag. Generated by Mistral Vibe. Co-Authored-By: Mistral Vibe --- SPEC.md | 38 ++++++++++++++++++++++++++------------ 1 file changed, 26 insertions(+), 12 deletions(-) diff --git a/SPEC.md b/SPEC.md index 2c3af81..95b4252 100644 --- a/SPEC.md +++ b/SPEC.md @@ -6,8 +6,8 @@ tool: it states every observable behavior (arguments, output, exit codes, environment variables, files written, packaging, checks). Change this file first when the behavior changes, then change the code and tests to match. -This checkout is an **empty template**: the CLI and quality gates are -ready; add scripts per section 6. +This checkout ships the CLI, the quality gates, and the registered +scripts; add new ones per section 6. @@ -40,8 +40,8 @@ daedalus [category...] list scripts (AND when multiple) daedalus … [args...] run when the script has every category ``` -In this template checkout, `SCRIPTS` is empty until the first script is -added (section 6). +The registry (section 4) is the source of truth for what is +registered today. - **1.3** The same tool runs on a Windows workstation and on a Linux host, either installed with pipx (section 9) or run from a checkout @@ -89,7 +89,8 @@ daedalus/ ├── ci/ # sanity.py, checks.py, with tests ├── autotest.py # Runs every check (local and CI) ├── pyproject.toml # Package, version, entry point, package data -├── requirements.txt # Test and lint tools +├── MANIFEST.in # Ships the placeholder script folders in sdists (SPEC item 9.2.1) +├── requirements.txt # Test, lint, and release tools ├── .gitea/workflows/ci.yml # CI job that runs autotest.py ├── .gitattributes # LF everywhere, CRLF for *.bat ├── .editorconfig # UTF-8, LF, final newline, 4 spaces (2 for yml/json/md) @@ -317,8 +318,7 @@ help. ## 4. Registry -`daedalus/registry.py` holds one dictionary. In this template checkout it -is empty until the first script is added: +`daedalus/registry.py` holds one dictionary of entries shaped like: ```python SCRIPTS: dict[str, Script] = { @@ -595,8 +595,10 @@ autotest results `pip install -r requirements.txt`, then `python autotest.py`. The sanity diff base is passed as `SANITY_DIFF_BASE`. - **7.11** `requirements.txt` holds the tools: `pytest`, `pytest-cov`, - `pycodestyle`, `pymarkdownlnt`, `pyyaml`, `shellcheck-py`, `setuptools`, - and `argcomplete` (the runtime dependency, so the completion tests run). + `pycodestyle`, `pymarkdownlnt`, `pyyaml`, `shellcheck-py`, + `setuptools`, `argcomplete` (the runtime dependency, so the + completion tests run), and `build` + `twine` (the release + tooling the publish script probes for, SPEC item 9.9). ## 8. Conventions @@ -625,10 +627,11 @@ autotest results | Command | Use | | --- | --- | -| `pipx install git+https://example.com/your-org/daedalus.git` | Own isolated environment, `daedalus` on `PATH` (recommended; works on Debian 12, where plain `pip install` is blocked) | +| `pipx install daedalus-tools` | From PyPI: own isolated environment, `daedalus` on `PATH` (the distribution name; works on Debian 12, where plain `pip install` is blocked) | +| `pipx install git+https://gitea.nolivaldeziii.com/nvaldez/daedalus.git` | From the public Git repository, same environment as above | | `pip install --user .` | From a checkout, into the user site | | `pip install -e .` | Development: the installed command runs the scripts in the checkout | -| `pipx upgrade daedalus` / `pip install --upgrade .` | Pick up new scripts | +| `pipx upgrade daedalus-tools` | Pick up a new PyPI release (Git installs: re-run the install block; `pipx upgrade` does not pull the repo, see [INSTALL](./INSTALL.md)) | - **9.2** The script folders are copied into the wheel under `daedalus/_library/`, with the same relative paths as in the repository: @@ -667,7 +670,7 @@ autotest results other third-party packages says so in its own help text and fails with a clear message when they are missing; `DAEDALUS_PYTHON` (SPEC item 5.2) points it at their environment. - Test and lint tools stay in `requirements.txt`. + Test, lint, and release tools stay in `requirements.txt`. - **9.7** Tests build the wheel from a copy of the checkout and check: - **9.7.1** Every registered script is at `daedalus/_library/`. - **9.7.2** No `/tests/`, `*.pyc`, or `.gitkeep` entry is present. @@ -678,6 +681,17 @@ autotest results import resolves. - **9.8** Bump `version` in `pyproject.toml` when scripts or the CLI change, so `pipx upgrade` picks them up. +- **9.9** Releasing: bump per 9.8, write the `CHANGELOG.md` entry, + commit, tag annotated `v`, move the `latest` tag, then + run `daedalus publish` - the guards section of + `python/src/publish/spec.md` (items 3.3-3.6) is the contract: + clean tree, `v` among `git tag --points-at HEAD`, + version free on PyPI, tooling present, chained build, twine + check, and with `--upload` exactly that version's artifacts. + Tag policy: one annotated `v` per release; `latest` + follows the newest; `stable` stays pinned until moved by hand. + A published version is immutable - the version-free guard + refuses a re-release by design. ## 10. Library imports