From 98398f7839bb300883009af6c4beaa6aa4e1c748 Mon Sep 17 00:00:00 2001 From: Cam Proudlock Date: Thu, 3 Sep 2026 18:53:20 -0400 Subject: [PATCH] docs: branch model documents one branch per instance --- CONTRIBUTING.md | 31 ++++++++++++++++++++++++------- 1 file changed, 24 insertions(+), 7 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5fddca00..83a739fe 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -171,15 +171,32 @@ Tests are required for: ## Branches: what belongs on main, and what does not -`main` is the product every site runs and the publication mirror exports. -`` branches hold work that is not ready for other sites to see. There are -two: `wj` here, and `wilm` on the corporate GitHub, where the other site -develops the .NET endpoint agent. +`main` is the curated product other sites adopt, and what the publication +mirror exports. It is a release decision: something reaching `main` says other +sites should take it. **`main` is not what this site runs.** + +Each branch answers to one instance: + +| branch | runs on | contains | +|---|---|---| +| `dev` | the dev instance | work being validated | +| `wj` | this site's PRODUCTION | everything this site runs | +| `main` | nothing directly | the curated release for other sites | +| `wilm` | the other site | their work, on the corporate GitHub | + +So work flows `dev` -> `wj` -> `main`: land it on `dev`, validate it on the dev +instance, take it to `wj` for production, and promote to `main` what you are +happy for another site to run. Promoting first and back-filling the site branch +is the wrong way round - it puts unvalidated work in front of other sites and +leaves production behind. + +`wilm` is not visible from the dev box because that machine has no account on +the corporate GitHub, which is why `fetch-wilm-branch.cmd` exists to bring it +back for review. It sits on the publication lineage, so it shares no ancestor +with `main`/`wj`/`dev` and cannot be merged locally. A site branch is not a fork. Both feed `main`, and the sooner they do it the -cheaper it is. A branch the dev box cannot see is still a branch: `wilm` is not -visible from here because this machine has no GitHub account, which is why -`fetch-wilm-branch.cmd` on the share exists to bring it back for review. +cheaper it is. **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