content(processes.develop): full dev workflow — logical flow + 11 steps
CD - Develop (guide → bcos.dev) / build-and-deploy (push) Has started running
CD - Develop (guide → bcos.dev) / build-and-deploy (push) Has started running
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
@@ -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-<name>` → `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 <type>/<issue>-<slug> → 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 <type>/<issue>-<slug>` → 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.
|
||||
|
||||
Reference in New Issue
Block a user