From b2e452c752ef50a7131833d81d7989074a7709c6 Mon Sep 17 00:00:00 2001 From: sneak Date: Tue, 29 Sep 2026 03:26:58 +0000 Subject: [PATCH] README development workflow: branch from and merge into next (closes #135) "Development workflow" and "For LLMs" said work branches off main and merges into main. They now say work branches from next, every pull request targets next, the repository manager squash-merges reviewed pull requests into next once make check is green, and only sneak merges next into main. The rest of both sections is unchanged. Model: opus-5-5 --- README.md | 24 ++++++++++++++---------- TODO.md | 5 +++++ 2 files changed, 19 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 2a9f82a..58d33c1 100644 --- a/README.md +++ b/README.md @@ -171,16 +171,19 @@ local cache is reliable, and the UI is responsive on a five-year-old laptop. All work on quak is test-driven. No exceptions. -1. Every change starts on a feature branch off `main`. +1. Every change starts on a feature branch off `next`, and its pull request + targets `next`. 2. The first commit on the branch is the test suite for what is being added or changed. Those tests must fail at that commit; the branch is red until the implementation lands. 3. Subsequent commits add the implementation and any refactors needed to make the tests pass. -4. A feature branch can only be merged into `main` when `make check` is green. - `main` is always green. CI runs `script/cibuild`, which builds the - `Dockerfile`: its `lint` and `test` phases, then the compile, so neither a - red branch nor one that does not compile can pass CI. +4. A pull request can only be merged into `next` when `make check` is green. + Once it has passed review, the repository manager squash-merges it into + `next`. Only sneak merges `next` into `main`. `main` and `next` are always + green. CI runs `script/cibuild`, which builds the `Dockerfile`: its `lint` + and `test` phases, then the compile, so neither a red branch nor one that + does not compile can pass CI. 5. Tests are the canonical API documentation for this library. Every test file is commented thoroughly enough that a reader who has never seen quak can learn how to use it from the tests alone. Comments explain why a behavior @@ -198,7 +201,7 @@ All work on quak is test-driven. No exceptions. not the tests, and so not the full `make check`. This is deliberate so the TDD red-phase commit (failing tests, no implementation yet) can land. The `test` phase is part of the image build, which is what CI executes via - `script/cibuild`, so a red branch still cannot reach `main`. + `script/cibuild`, so a red branch still cannot reach `next`. ## Design @@ -839,14 +842,15 @@ documents: `yarn.lock`. Never `git add -A`. Never force-push to main. - **The "Development workflow" section above.** All changes go on feature - branches. Tests are written first and committed in a failing state before the - implementation. Tests are the canonical API documentation and must be - commented thoroughly. `main` is always green. + branches off `next`, and every pull request targets `next`; only sneak merges + `next` into `main`. Tests are written first and committed in a failing state + before the implementation. Tests are the canonical API documentation and must + be commented thoroughly. `main` and `next` are always green. - **Required checks before every commit:** `make lint` must pass — that is eslint plus the prettier check, and it builds the `lint` phase of the `Dockerfile`, so it needs docker. The pre-commit hook enforces exactly that. - `make check` (which also runs the tests) must pass before merging to `main`. + `make check` (which also runs the tests) must pass before merging into `next`. `make fmt-check` is available for a host-side formatting check on its own, but it is not a separate requirement: `make lint` already covers it, and running both would check formatting twice. Never invoke eslint or prettier directly; diff --git a/TODO.md b/TODO.md index 0fafba7..ba35aec 100644 --- a/TODO.md +++ b/TODO.md @@ -22,6 +22,11 @@ declares one. # Completed Steps +- 2026-09-29: The README's "Development workflow" and "For LLMs" sections now + say work branches from `next`, every pull request targets `next`, the + repository manager squash-merges reviewed pull requests into `next`, and only + sneak merges `next` into `main` (issue 135). + - 2026-09-29: Brought the README and this file in line with `next` after the milestone merge (issue 132). The Next Step says no implementation work is open and the cache design (issue 36) waits on sneak's review. README corrections: -- 2.54.0