diff --git a/backend/src/main/resources/content/processes/develop/overview.md b/backend/src/main/resources/content/processes/develop/overview.md index 1d92742..a59a029 100644 --- a/backend/src/main/resources/content/processes/develop/overview.md +++ b/backend/src/main/resources/content/processes/develop/overview.md @@ -6,31 +6,92 @@ order: 10 audience: bcos --- -How day-to-day work flows on `develop`. **BCOS admin only.** +How day-to-day work flows from a reported issue to a production decision. **BCOS admin only.** ## The rule **Always work on `develop`, never `main` directly.** Every sub-project repo has branch protection on `main`. Before any change, `cd` into the sub-project and confirm you're on `develop` (or a -feature branch off it). - -**Repos that intentionally stay on `main`** (no `develop`): `hiveops-src` (monorepo root), +feature branch off it). Repos that intentionally stay on `main` (no `develop`): `hiveops-src`, `hiveops-docs`, `hiveops-release`, `hiveops-devops`. -## Flow -1. **`git pull` first** — remotes move; skipping this causes rebase/merge conflicts on push. -2. `cd /source/hiveops-src/hiveops-` → `git checkout develop`. -3. Make the change. For a new feature, branch off `develop`; for small/content changes, commit - straight to `develop` (established pattern). -4. Push → open a **PR to `develop`** for feature branches (CI build + tests must pass), then merge. -5. **Deploy to bcos.dev first and smoke-test** the real path before calling it done — a green - container is not a smoke test. Only then does it move toward `main` (see [[processes.main]]). +## Logical flow + +``` + ┌─ FEEDBACK GATE (upstream, human-owned — NOT Claude) ─┐ + │ users report → feedback.bcos.cloud │ + │ Josh + Tristan + Johannes triage │ + │ ◇ agreed valid? → they cut the Gitea issue │ + └───────────────────────┬───────────────────────────────┘ + ▼ ← Claude starts here + ① GITEA ISSUE exists (Bug/Enhancement) — no issue = don't start + ▼ + ② BRANCH GUARD ─ on develop / a branch off it? + ◇ another session open on a NON-develop branch? → ✋ STOP, flag Johannes + ▼ + ③ CODE ─ checkout develop → pull → branch /- → change + ▼ + ④ LOCAL VERIFY ─ frontend? run local dev server → Johannes eyeballs + ◇ good? ── no → back to ③ + ▼ yes + ⑤ PR → develop ─ Johannes APPROVES (UI) → Claude MERGES + ▼ + ⑥ cd-develop CI ─ wait for Slack 🟢 (no polling) + ◇ red? → Johannes notifies → back to ③ + ▼ green + ⑦ SMOKE TEST bcos.dev [HARD GATE] + Playwright (frontend) / API + real-JWT sweep (backend) + ◇ fail? → back to ③ + ▼ pass + ⑧ UPDATE THE GUIDE ─ affected module(s), relevant tabs + (Customer / Internal / Architect / Testing / Claude) + ▼ + ⑨ PR develop → main + ▼ + ⑩ RECONCILE ISSUE → place in milestone (e.g. 2026-08) + ▼ + ⑪ PROD DECISION (together) ─┬─ deploy now → prod process ([[processes.main]]) + └─ defer → next release window ([[processes.release]]) +``` + +## The steps + +1. **Gitea issue first.** Work starts from a **Gitea issue** (Bug/Enhancement). No issue = don't + start. User reports on **feedback.bcos.cloud** are triaged **by Josh / Tristan / Johannes** — if + they agree it's valid, *they* cut the Gitea issue. That triage is not Claude's step. See + [[processes.gitea-issues]]. +2. **Branch guard.** Confirm the working tree is on `develop` (or a branch off it). If Johannes has + **another session open on a non-`develop` branch**, STOP and flag it — never proceed in two + places. One session per working tree. +3. **Code.** `git checkout develop && git pull` → `git checkout -b /-` → make the + change. Describe the plan in one line and edit — no "can I code?" ask; the PR is the review. +4. **Local verify (UI).** For a **frontend** change, run a **local dev server** (`npm run dev`) so + Johannes can eyeball it. Proceed only once he confirms it's good. +5. **PR → `develop` → Johannes approves → Claude merges.** SOC2: he approves in the UI, Claude + merges via API. +6. **cd-develop CI → wait for GREEN** via the **Slack** notification. Do NOT poll CI (Gitea + run-status is buggy). If it's red, Johannes will notify. +7. **Smoke test bcos.dev — HARD GATE.** Against the live bcos.dev URL: **Playwright** for a + frontend change, **API + real-JWT curl sweep** for a backend change — every endpoint the change + touches, expected status **and** parseable body. "Deployed" is forbidden without this. +8. **Update the Guide.** For the module(s) affected, update the relevant **tabs** per what actually + changed (endpoints, tables, behaviour, how-to-test) so testers and the team read current docs. + Sync it now, at the bcos.dev-for-testers stage. +9. **PR `develop` → `main`.** +10. **Reconcile the issue** and place it in the target **milestone** (e.g. `2026-08`). Use `Refs #N` + in PRs, never `Fixes/Closes #N` (auto-close bypasses the Verify Fix → Tristan gate). Assign by + type: frontend → Tristan, backend → Johannes. +11. **Prod decision.** Decide **together**: manual build + deploy to production now + ([[processes.main]]), or leave it for the next release window ([[processes.release]]). + +**Human gates (Johannes):** ② stop-if-wrong-branch · ④ local UI sign-off · ⑤ PR approval · +⑥ red-CI notify · ⑪ prod decision. **Loop-backs to ③:** ④ verify fail, ⑥ CI red, ⑦ smoke fail. ## Conventions -- Conventional commits: `feat(scope): …`, `fix`, `chore`, `docs`, `content`. End commit messages - with the `Co-Authored-By: Claude …` line. +- Conventional commits: `feat(scope): …`, `fix`, `chore`, `docs`, `content`; end with the + `Co-Authored-By: Claude …` line. - **Commit before stopping** — never leave uncommitted work in any repo. -- **Issue first** — no code without a Gitea issue (see [[processes.gitea-issues]]). ## Do NOT - Do NOT commit directly to `main` or bypass branch protection. -- Do NOT skip the bcos.dev smoke test before promoting. +- Do NOT skip the bcos.dev smoke test (step 7) or the Guide update (step 8) before promoting. +- Do NOT triage feedback or cut issues off your own bat — that's the human Feedback gate.