From 6a2cbf2d031939ebee5434428613f6dcfb9eede8 Mon Sep 17 00:00:00 2001 From: Johannes Date: Thu, 16 Jul 2026 16:54:38 -0400 Subject: [PATCH] content(processes.develop): mark PRIMARY; sync diagram + frontend template/conformance + guide-audience rules Co-Authored-By: Claude Opus 4.8 --- .../content/processes/develop/overview.md | 71 ++++++++++++------- 1 file changed, 45 insertions(+), 26 deletions(-) diff --git a/backend/src/main/resources/content/processes/develop/overview.md b/backend/src/main/resources/content/processes/develop/overview.md index a59a029..5f079d6 100644 --- a/backend/src/main/resources/content/processes/develop/overview.md +++ b/backend/src/main/resources/content/processes/develop/overview.md @@ -8,11 +8,15 @@ audience: bcos How day-to-day work flows from a reported issue to a production decision. **BCOS admin only.** +> **This Guide page is the PRIMARY source of truth for the dev workflow.** The copy in +> `/source/claude/WAYS-OF-WORKING.md` §2.1 is a **secondary offline fallback** (for when bcos.dev is +> down). If they ever differ, this page wins — and update the fallback to match. + ## 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`, -`hiveops-docs`, `hiveops-release`, `hiveops-devops`. +on `main`. Confirm you're on `develop` (or a feature branch off it) before any change. Repos that +intentionally stay on `main` (no `develop`): `hiveops-src`, `hiveops-docs`, `hiveops-release`, +`hiveops-devops`. ## Logical flow @@ -23,12 +27,17 @@ feature branch off it). Repos that intentionally stay on `main` (no `develop`): │ ◇ agreed valid? → they cut the Gitea issue │ └───────────────────────┬───────────────────────────────┘ ▼ ← Claude starts here - ① GITEA ISSUE exists (Bug/Enhancement) — no issue = don't start + ① 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 + │ ┌─ FRONTEND (mandatory, read platform.frontend-template first) ───────┐ + │ │ • NEW page → COPY TablePage / TemplatePage, never from scratch │ + │ │ • EXISTING → FIRST verify it conforms to the template; │ + │ │ ◇ drifted? → bring into conformance, don't build on it│ + │ └─ svelte-template-lint hook enforces the locked components ──────────┘ ▼ ④ LOCAL VERIFY ─ frontend? run local dev server → Johannes eyeballs ◇ good? ── no → back to ③ @@ -42,8 +51,8 @@ feature branch off it). Repos that intentionally stay on `main` (no `develop`): Playwright (frontend) / API + real-JWT sweep (backend) ◇ fail? → back to ③ ▼ pass - ⑧ UPDATE THE GUIDE ─ affected module(s), relevant tabs - (Customer / Internal / Architect / Testing / Claude) + ⑧ UPDATE THE GUIDE ─ affected module(s), relevant tabs (own CI; no manual build) + bcos.dev guide = internal / ALL content · prod guide = CUSTOMER modules only ▼ ⑨ PR develop → main ▼ @@ -53,29 +62,41 @@ feature branch off it). Repos that intentionally stay on `main` (no `develop`): └─ defer → next release window ([[processes.release]]) ``` +**Human gates (Johannes):** ② wrong-branch stop · ④ UI sign-off · ⑤ PR approval · ⑥ red-CI notify · +⑪ prod decision. **Loop-backs to ③:** ④ verify fail · ⑥ CI red · ⑦ smoke fail. + ## 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 + they agree, *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. +2. **Branch guard.** Confirm the 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. +3. **Code.** `git checkout develop && git pull` → `git checkout -b /-` → change. + Describe the plan in one line and edit — no "can I code?" ask; the PR is the review. + **Frontend — MANDATORY (the #1 recurring double-work miss).** Before touching any `.svelte`, read + [[platform.frontend-template]]. + - **New page:** physically **COPY** the canonical base (`TablePage.svelte` plain tables / + `TemplatePage.svelte` badge pages) — never write from scratch — then edit only the allowed bits. + - **Existing page (new OR ongoing UI work — FIRST):** **verify it conforms** to the + TablePage/TemplatePage structure (`.filter-sidebar`, `.content-frame`, `.table-card` border, + active-filter chips, `Pagination` at top-of-table, dark-mode rules). Many pages have **drifted / + were never built from the template** — if so, bring it into conformance as part of the work; do + NOT build on top of a non-conformant page. The `svelte-template-lint` hook enforces the locks. 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. +5. **PR → `develop` → Johannes approves → Claude merges.** SOC2: he approves in the UI, Claude merges. +6. **cd-develop CI → wait for GREEN** via **Slack**. Do NOT poll CI (Gitea run-status is buggy). If + red, Johannes will notify. +7. **Smoke test bcos.dev — HARD GATE.** Live bcos.dev URL: **Playwright** (frontend) / **API + + real-JWT curl sweep** (backend) — 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. + changed. `hiveops-guide` has its **own cd-develop CI** (push develop → build → deploy bcos.dev → + smoke → Slack) — do NOT manual-build. **Audience rule:** the **bcos.dev guide is internal (ours), + ALL content**; the **production guide (`guide.bcos.cloud`) gets ONLY customer-audience modules** — + `processes.*`, `technical.*`, and `audience: bcos`/`internal` tabs never ship to prod. 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 @@ -83,9 +104,6 @@ feature branch off it). Repos that intentionally stay on `main` (no `develop`): 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 with the `Co-Authored-By: Claude …` line. @@ -93,5 +111,6 @@ feature branch off it). Repos that intentionally stay on `main` (no `develop`): ## Do NOT - Do NOT commit directly to `main` or bypass branch protection. -- 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. +- Do NOT skip the bcos.dev smoke test (⑦) or the Guide update (⑧) before promoting. +- Do NOT write a frontend page from scratch or build on a non-conformant one (③). +- Do NOT triage feedback or cut issues yourself — that's the human Feedback gate.