From 1cc725d4a769fc7b98322c09514246eb509bd948 Mon Sep 17 00:00:00 2001 From: cproudlock Date: Sun, 30 Aug 2026 09:00:09 -0400 Subject: [PATCH] Write down which branch work belongs on The convention existed only in the scripts' comments and in one conversation, which is not where somebody joining looks. CONTRIBUTING is. Records the two branches, the Scope trailer, the promote flow, and the point that most work is product: ADR-015 puts site differences in settings, seed data or scripts/site_imports//, so a site branch is about timing rather than locality. Also names the failure worth watching. Promoting something site-specific by accident is caught by the ADR-015 gate on the way into main. The real risk is product work stranded on a site branch because nobody decided, which is what turned wilm from a merge into a port. Scope: product (cherry picked from commit 1d4ac11572ed9e247d28fad8ebe019f993c4cf94) --- CONTRIBUTING.md | 45 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index db0f47aa..654127ef 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -151,6 +151,51 @@ Tests are required for: - New plugin hooks (contract test) - Schema migrations (before/after data integrity) +## Branches: what belongs on main, and what does not + +Two branches. `main` is the product every site runs and the publication mirror +exports. `` branches - currently `wj` - hold work that is not ready for +other sites to see. + +**Most work is product.** ADR-015 gives site differences three homes on `main`: +a setting with a neutral default, seed data, or a site-namespaced directory +(`scripts/site_imports//`, which the style gate exempts). That is the only +site-specific home in the tree, so a site branch is about TIMING, not locality: +things that are not ready yet, rather than things that are permanently ours. + +Say which at commit time, with a trailer, because the decision does not survive +being deferred - months later it is a list of subject lines and a guess: + +```bash +git commit -m "Add the thing" -m "Scope: product" # main should have it +git commit -m "Add the thing" -m "Scope: site" # this site alone +``` + +Then: + +```bash +tools/wj-status.sh # what is unpromoted, and where it belongs +tools/promote-to-main.sh --dry-run # what files would reach main +tools/promote-to-main.sh [ ...] # oldest first; runs main's gates +tools/git-push.sh main # you push, deliberately +``` + +Windows equivalents are `tools\git-push.cmd` and `tools\promote-to-main.cmd`. + +Promotion cherry-picks NAMED commits rather than merging the branch. Merging +takes the site work along with the product work, which is how a site branch +quietly becomes the product. + +**The failure to watch for is not what you think.** Promoting something +site-specific by accident is caught by the ADR-015 gate on the way into `main`. +The real risk is product work sitting on a site branch forever because nobody +decided - which is how the `wilm` branch stopped being a merge and became a +port, costing a MySQL dialect fix, a contract violation and a plugin install to +bring back. + +So rebase the site branch on `main` often, and promote as you go rather than in +one batch at the end. + ## Code review checklist - [ ] No underscores in table or column names