diff --git a/AGENTS.md b/AGENTS.md index 3d0c8f9..d9ead4e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -119,17 +119,22 @@ People trust FieldCraft with their models; a crash loses their work. **This outr contributors' pull requests wait for the maintainer's review (CONTRIBUTING.md). Never squash. Then remove your worktree and delete your local branch. 5. Never run the full gate locally: no `cargo xtask ci`, no `cargo clippy --workspace`, no - `cargo xtask wasm` or `oracle` unless step 2 calls for it. Never watch CI. GitHub CI runs - `cargo xtask ci` (fmt, assets, layers, clippy -D warnings, tests, wasm), the - oracle, the heavy tests and the dependency licences and advisories once per merge on `develop`; the coordinator + `cargo xtask wasm` or `oracle` unless step 2 calls for it. Never watch CI. GitHub CI runs, + per merge on `develop`, `cargo xtask ci --affected ` (fmt, assets, + layers on the whole tree; clippy and tests on the crates the change reaches; wasm when one + of them builds for it), the oracle and heavy tests when the change reaches the solvers or + the oracle, and the dependency licences and advisories; a change to Cargo.toml, Cargo.lock, + xtask or the workflows, the nightly run and every release run all of it (docs/releasing.md, + "What CI runs when"). `cargo xtask affected --base origin/develop` shows what your branch + reaches. The coordinator watches it and sends a failure back to the change that caused it, which is fixed forward at once. - **Keep the trunk gate fast** (under ~3 minutes on CI). A test that takes more than a few seconds (convergence studies, the whole corpus, cross-checks between solvers) is `#[ignore = "heavy: cargo xtask test --heavy (CI heavy job)"]`, with a fast representative test left in the trunk gate. The `heavy` CI job runs `cargo xtask test --heavy` (every ignored - test, benchmarks included, and the doc tests) on every merge to `develop`, nightly and on - demand (`gh workflow run CI --ref `). Hostile-input tests run commands on sessions with small + test, benchmarks included, and the doc tests) on merges to `develop` that reach a crate with + heavy tests, nightly, before every release and on demand (`gh workflow run CI --ref `). Hostile-input tests run commands on sessions with small work caps (`Session::limits`) so refusals are instant; never lower the production caps for a test. - **Publishing**: `origin` is github.com/jyviko/fieldcraft. Changes land through pull requests diff --git a/docs/releasing.md b/docs/releasing.md index 69274ee..70b0506 100644 --- a/docs/releasing.md +++ b/docs/releasing.md @@ -159,13 +159,31 @@ git push origin :main # fast-forward main to the verified develop c ``` `main` holds released code only: it moves only by fast-forwarding to a verified `develop` -commit (a maintainer push; the branch is protected), never by merges, rewrites or force-pushes. The run builds the three platforms; when +commit (a maintainer push; the branch is protected), never by merges, rewrites or force-pushes. The run +first verifies the commit with everything CI has (see below); then it builds the three platforms; when all succeed, the last job checks that every file is there, writes `SHA256SUMS.txt` and the notes, and creates the draft `FieldCraft v` targeting the pushed commit. Pushing `main` again with the same version rebuilds and replaces the draft's files (its notes are kept). The job refuses a version whose tag exists or whose release is already published: bump the version instead. +## What CI runs when + +| When | What runs | +|---|---| +| Push to `develop` | `plan` takes the newest `develop` commit whose CI run passed as the base and runs `cargo xtask affected --base `. `cargo xtask ci --affected `: fmt, assets, layers (always, whole tree), then clippy and the tests of the changed crates and every crate that depends on them, and the wasm check when one of them builds for wasm. `heavy` (`cargo xtask test --heavy`) and `oracle` run only when the change reaches the solvers or the oracle (`solver`), or everything. A newer push cancels the run before it; the next one tests everything since the last green run, so nothing is skipped. | +| Change to `Cargo.toml`, `Cargo.lock`, the toolchain, `xtask/` or `.github/` | Everything: the full gate, heavy and oracle (`everything`). | +| Pull request from a fork or Dependabot | The same plan against the pull request's merge base; never the heavy job. | +| Nightly (03:23 UTC) and `gh workflow run CI --ref ` | Everything: the full `cargo xtask ci`, heavy and oracle on Linux (manual runs add the macOS oracle). | +| Weekly (Sunday) | The oracle on macOS. | +| Release (`release.yml`, push to `main` and dry runs) | `verify-ci` (full `cargo xtask ci`), `verify-heavy`, and `verify-oracle` on Linux and macOS; every packaging job needs all of them. | + +`cargo xtask affected --base [--head ]` prints the plan for any range, e.g. what a +commit needs: `cargo xtask affected --base ^ --head `. A file outside every crate +(`tests/oracle/…`, `assets/…`) belongs to the crates whose sources name its top-level directory; +`solver` is set when the affected crates include the oracle's (`fieldcraft-testkit`) or one with +`#[ignore]`d heavy tests. + ## Verify and publish Publishing is a maintainer's call; an agent preparing a release stops at the draft. @@ -189,7 +207,7 @@ Publishing is a maintainer's call; an agent preparing a release stops at the dra ## Dry runs -`gh workflow run release.yml -R jyviko/fieldcraft --ref ` builds every package and +`gh workflow run release.yml -R jyviko/fieldcraft --ref ` runs the verify jobs, then builds every package and uploads them with the notes as the `release-assets` artifact of the run, without creating a release. `-f draft=true` creates or updates the draft, and is accepted on `main` only. Locally, `packaging/macos/package.sh --arch aarch64` (or `x86_64`, `universal`) and