1 Commits

Author SHA1 Message Date
nvaldez cfbb66ce39 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<version> 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 <vibe@mistral.ai>
2026-11-19 11:10:28 +01:00
+26 -12
View File
@@ -6,8 +6,8 @@ tool: it states every observable behavior (arguments, output, exit codes,
environment variables, files written, packaging, checks). Change this file environment variables, files written, packaging, checks). Change this file
first when the behavior changes, then change the code and tests to match. 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 This checkout ships the CLI, the quality gates, and the registered
ready; add scripts per section 6. scripts; add new ones per section 6.
<!-- toc-start: headings 2..6 --> <!-- toc-start: headings 2..6 -->
@@ -40,8 +40,8 @@ daedalus <category> [category...] list scripts (AND when multiple)
daedalus <category>… <name> [args...] run when the script has every category daedalus <category>… <name> [args...] run when the script has every category
``` ```
In this template checkout, `SCRIPTS` is empty until the first script is The registry (section 4) is the source of truth for what is
added (section 6). registered today.
- **1.3** The same tool runs on a Windows workstation and on a Linux - **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 host, either installed with pipx (section 9) or run from a checkout
@@ -89,7 +89,8 @@ daedalus/
├── ci/ # sanity.py, checks.py, with tests ├── ci/ # sanity.py, checks.py, with tests
├── autotest.py # Runs every check (local and CI) ├── autotest.py # Runs every check (local and CI)
├── pyproject.toml # Package, version, entry point, package data ├── 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 ├── .gitea/workflows/ci.yml # CI job that runs autotest.py
├── .gitattributes # LF everywhere, CRLF for *.bat ├── .gitattributes # LF everywhere, CRLF for *.bat
├── .editorconfig # UTF-8, LF, final newline, 4 spaces (2 for yml/json/md) ├── .editorconfig # UTF-8, LF, final newline, 4 spaces (2 for yml/json/md)
@@ -317,8 +318,7 @@ help.
## 4. Registry ## 4. Registry
`daedalus/registry.py` holds one dictionary. In this template checkout it `daedalus/registry.py` holds one dictionary of entries shaped like:
is empty until the first script is added:
```python ```python
SCRIPTS: dict[str, Script] = { SCRIPTS: dict[str, Script] = {
@@ -595,8 +595,10 @@ autotest results
`pip install -r requirements.txt`, then `python autotest.py`. The `pip install -r requirements.txt`, then `python autotest.py`. The
sanity diff base is passed as `SANITY_DIFF_BASE`. sanity diff base is passed as `SANITY_DIFF_BASE`.
- **7.11** `requirements.txt` holds the tools: `pytest`, `pytest-cov`, - **7.11** `requirements.txt` holds the tools: `pytest`, `pytest-cov`,
`pycodestyle`, `pymarkdownlnt`, `pyyaml`, `shellcheck-py`, `setuptools`, `pycodestyle`, `pymarkdownlnt`, `pyyaml`, `shellcheck-py`,
and `argcomplete` (the runtime dependency, so the completion tests run). `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 ## 8. Conventions
@@ -625,10 +627,11 @@ autotest results
| Command | Use | | 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 --user .` | From a checkout, into the user site |
| `pip install -e .` | Development: the installed command runs the scripts in the checkout | | `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 - **9.2** The script folders are copied into the wheel under
`daedalus/_library/`, with the same relative paths as in the repository: `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 other third-party packages says so in its own help text and fails
with a clear message when they are missing; with a clear message when they are missing;
`DAEDALUS_PYTHON` (SPEC item 5.2) points it at their environment. `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** Tests build the wheel from a copy of the checkout and check:
- **9.7.1** Every registered script is at `daedalus/_library/<path>`. - **9.7.1** Every registered script is at `daedalus/_library/<path>`.
- **9.7.2** No `/tests/`, `*.pyc`, or `.gitkeep` entry is present. - **9.7.2** No `/tests/`, `*.pyc`, or `.gitkeep` entry is present.
@@ -678,6 +681,17 @@ autotest results
import resolves. import resolves.
- **9.8** Bump `version` in `pyproject.toml` when scripts or the CLI - **9.8** Bump `version` in `pyproject.toml` when scripts or the CLI
change, so `pipx upgrade` picks them up. change, so `pipx upgrade` picks them up.
- **9.9** Releasing: bump per 9.8, write the `CHANGELOG.md` entry,
commit, tag annotated `v<version>`, 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<version>` 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<version>` 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 ## 10. Library imports