From 47ef29c3d97a9b7b6a8b6c3c33f143cd4e69db63 Mon Sep 17 00:00:00 2001 From: Sarah Date: Fri, 20 Nov 2026 15:48:49 -0800 Subject: [PATCH] Pull requests are squash-merged; merge commits stay allowed for the rare case that needs one --- AGENTS.md | 2 +- CONTRIBUTING.md | 2 +- docs/DESIGN.md | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index f9f1225..560afc3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -68,4 +68,4 @@ A tool exists because a question needed it. Do not add tools, commands, or optio ## Commits and pull requests -A commit message is one sentence stating the behavior. A tool arrives as a pull request whose record is committed with it. Merge with a merge commit (`gh pr merge --merge`): `promote` runs on the merge commit, and flyloft watches that check. +A commit message is one sentence stating the behavior. A tool arrives as a pull request whose record is committed with it. Squash-merge it (`gh pr merge --squash`): `promote` runs on the commit that lands on `main`, and flyloft watches that check. Merge commits stay allowed for the rare case that needs one. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8ce04b3..8bfbdf5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -85,7 +85,7 @@ Any change under `tools//` bumps `metadata.version`, prose included. A pub 1. Push your branch and open the pull request. 2. `check` runs: the tool's rules, an unpublished version, a public amd64 candidate for the branch's source, and a record of that candidate's passing test. -3. A member other than you reviews it: does the skill describe what the Containerfile builds, does the test exercise every documented command, are the weights in the image, is every example a full command line, and does the record show the test ran on the hardware the tool needs (its node and GPU lines) and gave the known answers. They merge with a merge commit. +3. A member other than you reviews it: does the skill describe what the Containerfile builds, does the test exercise every documented command, are the weights in the image, is every example a full command line, and does the record show the test ran on the hardware the tool needs (its node and GPU lines) and gave the known answers. They squash-merge it. 4. `promote` copies the candidate to `:`. ## Weights behind a login diff --git a/docs/DESIGN.md b/docs/DESIGN.md index e2dea8b..03852cd 100644 --- a/docs/DESIGN.md +++ b/docs/DESIGN.md @@ -73,7 +73,7 @@ scripts/promote copy a candidate to its version tag, never overwriting - `seed`, `seed.yml`, on dispatch only, with `GITHUB_TOKEN`: the placeholder that creates a tool's package; it checks out nothing and runs no Containerfile. - `check`, on every pull request: the skill's frontmatter parses and its name is the directory's; a Containerfile and `test/run.sh` exist; the version is not in the registry; the candidate `src-` is in the registry and is `linux/amd64`; the record exists for this version, names the candidate's digest, and shows exit code 0. -- `promote`, on a push to `main`, for the tools the push changed: the candidate tag, computed from the merge commit's tree, copied to the version tag (`skopeo copy` within the registry writes a manifest and moves no layers). A version tag that already holds the candidate's digest passes, so a re-run after a partial failure completes; one that holds anything else fails. A tool whose candidate this registry has never seen is skipped, with a line saying so: it was merged in from another shed, as the scratch shed takes the real shed's tools, and its image lives in that shed's registry. It runs on the push, not on the pull request's close, so that its check attaches to the merge commit, which is what flyloft watches. +- `promote`, on a push to `main`, for the tools the push changed: the candidate tag, computed from the merged commit's tree, copied to the version tag (`skopeo copy` within the registry writes a manifest and moves no layers). A version tag that already holds the candidate's digest passes, so a re-run after a partial failure completes; one that holds anything else fails. A tool whose candidate this registry has never seen is skipped, with a line saying so: it was merged in from another shed, as the scratch shed takes the real shed's tools, and its image lives in that shed's registry. It runs on the push, not on the pull request's close, so that its check attaches to the commit that lands on `main`, which is what flyloft watches. **Guards.** Nothing a pull request contains runs on the lab's machines: CI builds nothing and runs nothing but the check script and its unit test, on GitHub's hosted runners. A fork's pull request gets `check` with a read-only token and the public registry. What a published image contains is what an organization member built and pushed, as for any of the lab's code. The trust boundary is the organization's membership. `main` requires `check` to pass and takes no other required approval: flyloft merges as the campaign's owner, a member, after its critic's review, and a person's pull request is merged by a member other than its builder (§3). Nothing that goes public holds a credential: `check.py` scans a tool's directory and a test's record for the shapes of tokens, keys, and credential files, and refuses an `ARG` or `ENV` that would bake one into an image; `scripts/build` refuses before anything is built or pushed, `scripts/record` before a record is written, and `check` refuses the pull request as the backstop, each naming the file, the line, and the fix. What it cannot see is a credential a `RUN` step fetches and writes into a layer; scanning layers is deferred (§7). @@ -95,7 +95,7 @@ The shed has no test tier of its own beyond the unit tests of its scripts: it is ## 6. How flyloft uses the shed -Designed in flyloft's `docs/design/toolshed.md`. In short: flyloft keeps a clone at `origin/main` and renders the catalogue (name, version, description, skill path) into its implementers' assignments; a run may name `tool="name@version"`, and its job then runs inside the tool's image with the work directory mounted; an implementer that needs a tool the shed lacks writes it in a worktree of the shed and submits it; flyloft builds and pushes the candidate on its host, with `gh` signed in so that `scripts/push` can have the seed workflow create a new tool's package; runs `scripts/test` against it as a run of the campaign on the campaign's cluster and budget, commits the record, pushes the branch and opens the pull request, waits for `check`, has its critic review the pull request and the record, merges with a merge commit, and watches the merge commit's `promote` check; then the campaign calls the published version. One tool build at a time per campaign. +Designed in flyloft's `docs/design/toolshed.md`. In short: flyloft keeps a clone at `origin/main` and renders the catalogue (name, version, description, skill path) into its implementers' assignments; a run may name `tool="name@version"`, and its job then runs inside the tool's image with the work directory mounted; an implementer that needs a tool the shed lacks writes it in a worktree of the shed and submits it; flyloft builds and pushes the candidate on its host, with `gh` signed in so that `scripts/push` can have the seed workflow create a new tool's package; runs `scripts/test` against it as a run of the campaign on the campaign's cluster and budget, commits the record, pushes the branch and opens the pull request, waits for `check`, has its critic review the pull request and the record, squash-merges it, and watches the squash commit's `promote` check; then the campaign calls the published version. One tool build at a time per campaign. ## 7. Deferred