diff --git a/.planning/STATE.md b/.planning/STATE.md index 26e65245f..ec06e3019 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -30,9 +30,9 @@ B1 dispatches. ### F2 — Document branch + release model -- [ ] Extend `CONTRIBUTING.md` with branch flow + ASCII/Mermaid diagram -- [ ] Mirror page on healthlog-docs (developer / contributor docs) -- [ ] Make user-vs-contributor distinction explicit +- [x] Extend `CONTRIBUTING.md` with branch flow + ASCII diagram (this branch) +- [x] Mirror page on healthlog-docs at `/contributing/branch-model/` (`5d96861` on healthlog-docs/main) +- [x] User-vs-contributor distinction explicit in both surfaces - Detailed report: `.planning/phase-F2-report.md` ### FX — User-facing artifact cleanup (PII + jargon + German leaks) diff --git a/.planning/phase-F2-report.md b/.planning/phase-F2-report.md new file mode 100644 index 000000000..7b7bd18d1 --- /dev/null +++ b/.planning/phase-F2-report.md @@ -0,0 +1,47 @@ +# Phase F2 — Document branch + release model + +Status: complete · 2026-05-10T15:18+02:00 + +## Outcome + +The two-branch model is documented in two places: + +| Surface | File | Audience | +|---|---|---| +| Repo root | `CONTRIBUTING.md` (extended) | Contributors cloning the repo | +| Docs site | `src/content/docs/contributing/branch-model.mdx` | End users + would-be contributors browsing docs.healthlog.dev | + +Both contain: + +- ASCII branch-flow diagram (`feature/* → develop → main → tag → GHCR → Coolify`) +- Two-rule summary (develop = daily, main = release-only) +- Hotfix flow (branch from main, tag patch, merge back to develop) +- Explicit "end users follow tags / contributors track develop" guidance + +## Commits + +| Repo | Commit | Branch | +|---|---|---| +| HealthLog | (this commit) | `develop` | +| healthlog-docs | `5d96861` | `main` | + +## Build verification + +`healthlog-docs`: `npm run build` green, 46 pages built (was 45), +new `/contributing/branch-model/` slug rendered, pagefind search +index covers it. + +## Why this lands now (before B-phase work) + +The branch model is operational: every B1-B5 commit goes to `develop`. +If the docs lag behind the operational reality, would-be contributors +who clone the repo today and open a PR against `main` would need to +re-target it. Docs ship with F2 so that contract is clear from the +first v1.4.20 commit. + +## Sidebar placement + +The new "Contributing" sidebar group sits at the bottom of the docs +nav, below "Account". Contains one entry today (`branch-model`); F5 +or future hygiene PRs may add `code-conventions`, +`dev-environment`, etc. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e7e5126d0..0824ab103 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -90,13 +90,39 @@ pnpm db:generate # Regenerates Prisma client Always include the migration file in your PR. +## Branch Model + +HealthLog uses a long-lived `develop` branch for daily work and reserves `main` for releases. + +``` + feature/* ──┐ + ├──► develop ──► (release-merge) ──► main ──► tag vX.Y.Z ──► GHCR build ──► Coolify deploy + fix/* ──┘ │ + └──► hotfix/* ──► main + tag, then merge back to develop +``` + +Two simple rules: + +- **`develop` is the daily target.** Open feature, fix, test, and docs PRs against `develop`. Builds do not run on `develop` pushes — the branch is free of release ceremony. +- **`main` is release-only.** It receives a single release-merge per version, gets tagged (`v1.4.20`, etc.), and that tag is what triggers the Docker image build, the GHCR push, and the Coolify deploy. Pushes to `main` outside a release are reserved for hotfixes that cannot wait for the next cycle. + +If a critical bug needs a hotfix: + +1. Branch from `main`: `git checkout -b hotfix/something main` +2. Land the fix; tag a patch release on `main` +3. Merge `main` back into `develop` so the next release inherits the fix + +End users: track the latest `v*` tag (or `:latest` on GHCR). The `main` branch always equals the latest release. + +Contributors: track `develop`. PRs target `develop`. + ## Pull Requests 1. Fork the repository -2. Create a feature branch (`git checkout -b feature/your-feature`) +2. Create a feature branch off `develop` (`git checkout -b feature/your-feature develop`) 3. Make your changes 4. Ensure all checks pass (`pnpm typecheck && pnpm lint && pnpm test && pnpm format:check && pnpm build`) -5. Submit a PR with a clear description of the changes +5. Submit a PR against `develop` with a clear description of the changes ## Security