content(processes.develop): mark PRIMARY; sync diagram + frontend template/conformance + guide-audience rules
CD - Develop (guide → bcos.dev) / build-and-deploy (push) Successful in 52s
CD - Develop (guide → bcos.dev) / build-and-deploy (push) Successful in 52s
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
@@ -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 <type>/<issue>-<slug> → 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 <type>/<issue>-<slug>` → 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 <type>/<issue>-<slug>` → 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.
|
||||
|
||||
Reference in New Issue
Block a user