docs: branch model documents one branch per instance
Some checks failed
CI / naming (push) Successful in 3s
CI / frontend (push) Successful in 1m37s
CI / migrations-mysql (push) Successful in 42s
CI / backend (push) Failing after 4m49s

CONTRIBUTING.md still said "main is the product every site runs and the
publication mirror exports" and framed wj/wilm as site branches feeding it.
That was true when main was the only thing anyone deployed. It is not now:
WJ production runs wj, the /ops instance runs dev, and main deploys nowhere.
Nothing in the repository mentioned dev at all, so the branch a deploy script
refuses to run without was undocumented.

Replaces that section with the branch/instance table and the dev -> wj -> main
promotion order, and says why promoting before validating is the wrong way
round. Keeps the wilm note but moves it up with the reason it cannot be
merged locally: it sits on the publication lineage and shares no ancestor.

CLAUDE.md gains the branch-to-server pointer and records that
export-github.sh now builds a dist only for wj and dev.

docs/DEPLOY.md is deliberately left alone: `git pull origin main` is correct
there. That document is the generic connected-Docker deploy another site
follows, and main is exactly what another site adopts.

Scope: product
This commit is contained in:
cproudlock
2026-09-03 18:52:55 -04:00
parent b5737f47c1
commit bfc30f4c7c
2 changed files with 28 additions and 8 deletions

View File

@@ -36,6 +36,7 @@ should be typed here again.
| what the collector sends | `docs/COLLECTOR-INTEGRATION.md`, ADR-006 | | what the collector sends | `docs/COLLECTOR-INTEGRATION.md`, ADR-006 |
| how a site is deployed | `docs/INSTALL-WINDOWS.md`, `docs/OPERATE-WINDOWS.md` | | how a site is deployed | `docs/INSTALL-WINDOWS.md`, `docs/OPERATE-WINDOWS.md` |
| how code reaches GitHub | `tools/export-github.sh` | | how code reaches GitHub | `tools/export-github.sh` |
| which branch reaches which server | `devnotes/deploy-and-branch-model.html` |
## Standards are gates, not prose ## Standards are gates, not prose
@@ -102,7 +103,9 @@ surface and always ships.
- `shopdb/plugins/loader.py` - discovery and dependency-aware loading - `shopdb/plugins/loader.py` - discovery and dependency-aware loading
- `shopdb/plugins/alembic_template.py` - the env every plugin chain runs through - `shopdb/plugins/alembic_template.py` - the env every plugin chain runs through
- `frontend/src/router/index.js`, `frontend/src/components/AppSidebar.vue` - `frontend/src/router/index.js`, `frontend/src/components/AppSidebar.vue`
- `tools/export-github.sh` - scrub and publication gate - `tools/export-github.sh` - scrub and publication gate; builds the dist for
the branch it is on (`wj` -> /shopdb, `dev` -> /ops) and refuses on any other
- `tools/mirror-wilm.sh` - push a carried wilm bundle to gitea
## State ## State

View File

@@ -171,15 +171,32 @@ Tests are required for:
## Branches: what belongs on main, and what does not ## Branches: what belongs on main, and what does not
`main` is the product every site runs and the publication mirror exports. `main` is the curated product other sites adopt, and what the publication
`<site>` branches hold work that is not ready for other sites to see. There are mirror exports. It is a release decision: something reaching `main` says other
two: `wj` here, and `wilm` on the corporate GitHub, where the other site sites should take it. **`main` is not what this site runs.**
develops the .NET endpoint agent.
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 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 cheaper it is.
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.
**Most work is product.** ADR-015 gives site differences three homes on `main`: **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 a setting with a neutral default, seed data, or a site-namespaced directory