From 1e4558831e5c26f9ec1e6737f0a4eceb34b79d7b Mon Sep 17 00:00:00 2001 From: Jer Miller Date: Sun, 19 Jul 2026 12:48:19 -0600 Subject: [PATCH] docs: focus development validation --- AGENTS.md | 21 ++++++++++++------- CONTRIBUTING.md | 8 +++++-- README.md | 3 ++- .../post-action-navigation-walkthrough.md | 5 +++-- docs/health_imports.md | 3 ++- docs/testing.md | 6 +++--- 6 files changed, 30 insertions(+), 16 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index e0b813fa3..19def4d36 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -89,7 +89,6 @@ Verified against `Makefile`. Grouped by use. | Target | When to use | |--------|-------------| | `make install` | First setup and whenever `pyproject.toml` or `uv.lock` changes. Creates `.venv/`, syncs deps, runs `make skills`. | -| `make hopper-install` | Lean lode bootstrap — builds only `.installed` (venv + dev/host deps + skills) so `make ci` runs. Intentionally skips runtime/model provisioning (no `install-models`, parakeet build, or CUDA validation). | | `make skills` | Regenerate generated router references, then rewrite the `sol` + `journal` router skill symlinks into `journal/`. (`make install` depends on this; rarely run alone.) | | `make update` | Upgrade all deps to latest, regenerate `uv.lock`. Expect test churn. | | `make update-prices` | Refresh genai-prices model-cost data when adding a new provider model or when pricing tests fail. | @@ -110,17 +109,25 @@ Verified against `Makefile`. Grouped by use. |--------|-------------| | `make format` | Auto-fix formatting and imports with ruff. Safe to run anytime; modifies files. | | `make format-check` | Format dry-run. Part of `make ci`; rarely run alone. | -| `make test` | All unit tests — `tests/` + every `solstone/apps/*/tests/`, one parallel run. Format-check runs first; failures block tests. Fast inner loop. | -| `make test-cov` | Same suite with full-repo terminal coverage; used by `make ci` / `make verify`. | +| `make test` | Full unit suite — `tests/` + every `solstone/apps/*/tests/`, one parallel run. Format-check runs first; failures block tests. | +| `make test-cov` | Same suite with full-repo terminal coverage; used by `make verify`. | | `make test-app APP=` | Run a single app's tests (focus helper). | | `make test-only TEST=` | Run a specific test file or pytest node id (`TEST="-k test_name"` also works). | | `make coverage` | HTML coverage report under `htmlcov/`. Occasional. | | `make watch` | pytest-watch — reruns tests on file change. Useful during a test-heavy sprint. | -| `make ci` | Format-check + ruff + layer-hygiene + coverage tests. **Run before every commit.** | -| `make verify` | Same steps as `make ci`. Either name is fine. | +| `make ci` | Install checks plus the full unit suite. Canonical final-tree gate before merge or release. | +| `make verify` | Install checks plus the coverage suite. Use when coverage is specifically required. | | `make install-checks` | The pre-test half of `make ci` (format-check + ruff + layer-hygiene). Called by `ci` / `verify`. | | `make check-layer-hygiene` | Run `scripts/check_layer_hygiene.py` alone. Useful when iterating on an L1–L2 violation flagged by CI. | +During development, use the narrowest checks that prove the changed behavior: +`make test-only`, `make test-app`, and specific `make check-*` targets. Run +`make ci` once on the settled final tree before merge or release. Run it +earlier only for changes to CI/test infrastructure, shared fixtures, packaging +or dependencies, broad cross-cutting contracts, or when a clean baseline is +necessary to diagnose the task. Do not rerun an unchanged failure merely to +seek green. + ### Verification against a running sandbox | Target | When to use | @@ -140,7 +147,7 @@ Verified against `Makefile`. Grouped by use. | Target | When to use | |--------|-------------| -| `make pre-commit` | Install pre-commit hooks (optional; most coders rely on `make ci` directly). | +| `make pre-commit` | Install pre-commit hooks (optional). | | `make versions` | Print versions of Python, uv, and key deps. Diagnostic. | ### Don't use @@ -313,7 +320,7 @@ Generic software principles (DRY, KISS, YAGNI, single responsibility, small focu ## 10. Commit hygiene - Small, focused commits with descriptive messages. -- Run `make ci` before every commit. +- Validate each commit with focused checks appropriate to its diff. The full `make ci` gate belongs on the final tree before merge or release, not before every intermediate commit. - Run `git` commands directly — not `git -C` — you're already in the repo. - Don't commit runtime artifacts written under `tests/fixtures/journal/` by `make dev` / `make sandbox` (`.gitignore` covers them; verify with `git status` anyway). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1e9909018..968d6a739 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -109,13 +109,17 @@ For app work, read [docs/APPS.md](docs/APPS.md) before changing `solstone/apps/` Use the Makefile targets. The high-signal commands are: ```bash -make test make test-only TEST=tests/test_utils.py::test_foo make test-app APP=settings +make test make ci ``` -`make test` runs all unit tests — `tests/` plus every `solstone/apps/*/tests/`, in one parallel run — after a format check. `make ci` is the pre-commit gate: format-check, ruff, layer hygiene, and tests. Run it before committing. +Use `make test-only` and `make test-app` as the development loop. `make test` +runs all unit tests — `tests/` plus every `solstone/apps/*/tests/`, in one +parallel run — after a format check. `make ci` is the canonical full gate: +install checks plus the full unit suite. Run it once on the settled final tree +before submitting, merging, or releasing, not before every intermediate commit. ```bash make test-only TEST="-k test_foo" # one test by name/pattern diff --git a/README.md b/README.md index 4066942da..609ca4ca3 100644 --- a/README.md +++ b/README.md @@ -128,7 +128,8 @@ Run `sol help` for the full command reference. See [AGENTS.md](AGENTS.md) for development guidelines, coding standards, and testing instructions. -Use `make dev` to run the full stack against test fixtures and `make ci` for pre-commit checks. +Use `make dev` to run the full stack against test fixtures, focused test targets +during development, and `make ci` on the final tree before merge or release. ## feedback diff --git a/docs/design/post-action-navigation-walkthrough.md b/docs/design/post-action-navigation-walkthrough.md index fd989e1d9..157896185 100644 --- a/docs/design/post-action-navigation-walkthrough.md +++ b/docs/design/post-action-navigation-walkthrough.md @@ -42,9 +42,10 @@ Use this recipe on a fresh or sandbox journal to verify the facet-detail and Nee Run: ```sh -make ci -make test make test-app APP=settings + +# Final-tree gate before merge or release +make ci ``` Use `make verify-api` when API baseline coverage is being audited for this route set. diff --git a/docs/health_imports.md b/docs/health_imports.md index d04b8e028..d8137df27 100644 --- a/docs/health_imports.md +++ b/docs/health_imports.md @@ -132,4 +132,5 @@ Run these before treating health import changes as complete: - `make check-journal-io-access` - `make check-journal-io-mechanic` -Run `make ci` before committing or handing this to a release branch. +Use the focused checks above while iterating. Run `make ci` once on the settled +final tree before merge or release. diff --git a/docs/testing.md b/docs/testing.md index b8ee5c9cd..8efdb788f 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -2,7 +2,7 @@ ## Test Structure -- **Framework**: pytest; coverage reporting comes from `make test-cov`, `make ci`, or `make coverage`, not bare `make test` +- **Framework**: pytest; coverage reporting comes from `make test-cov`, `make verify`, or `make coverage`, not `make test` or `make ci` - **Unit Tests**: live under `tests/` (and each app's `tests/` dir) - Fast, no external API calls, no real browser - Use `tests/fixtures/journal/` mock data @@ -25,9 +25,9 @@ The `tests/fixtures/journal/` directory contains a complete mock journal structu - `make test` runs all unit tests — `tests/` + every `solstone/apps/*/tests/`, in one parallel run - `make test-cov` — the same suite with coverage reporting -- `make test-app APP=` to run a single app's tests; `make test-only TEST=path` for a specific file/pattern +- `make test-app APP=` and `make test-only TEST=path` are the focused development loop - `make coverage` to generate a coverage report -- `make ci` before committing (formats, lints, tests) +- `make ci` once on the settled final tree before merge or release (install checks plus the full unit suite) - Always run `journal restart-convey` after editing `solstone/convey/` or `solstone/apps/` to reload code ## OpenAPI Verification Lanes -- 2.51.2