shanshanzhong147
f6f2ca9a29
owner 反馈 GitHub Actions UI 上 'Build image and deploy to staging' 等英文 job 名、'Docker Build summary / Build inputs / Build records include...' 等英文 summary 文本不符合中文开发者团队约定。 ## 汉化（全部显示字段） - ci.yml: workflow name '持续集成'、job '构建/Vet/测试' 和 'golangci-lint'、 所有 step name 中文（保留 golangci-lint / Go 等工具名） - deploy-staging.yml: workflow name '测试环境部署'、job '构建镜像并部署到 测试环境'、11 个 step name 中文 - doc/development-workflow-zh.md: 同步 4 处对 'Deploy Staging' 显示名的 引用，改为 '测试环境部署 (deploy-staging.yml)' 形式，以文件名锚定 ## 关闭 docker/build-push-action 英文 summary deploy-staging.yml workflow env 加 DOCKER_BUILD_SUMMARY=false。原来跑完 build 那个英文 'Docker Build summary / Build inputs / ...' 块在 GitHub Actions UI 上不再出现。部署结果靠 Telegram 通知传递。 ## actions 升级到支持 Node 24 的版本 GitHub Runner 报 Node 20 deprecated 警告，9 月 16 日强制移除。本次一次 性升级到当前 latest： - actions/checkout v4 -> v6 - actions/setup-go v5 -> v6 - docker/setup-buildx-action v3 -> v4 - docker/build-push-action v6 -> v7 - appleboy/scp-action v0.1.7 -> v1.0.0 (正式版) - appleboy/ssh-action v1.0.3 -> v1.2.5 - golangci/golangci-lint-action v6 -> v9 (Node 24，仍支持 version: latest 和 only-new-issues: true) 不改: - workflow .yml 文件名（gh CLI / 文档引用都用文件名锚定，不动） - secret 名 / env var 名（约定俗成全大写英文） - Telegram 通知正文（本来就是中文） ## 后续 agent prompt（架构师/QA/devops）里引用 'Build, vet, test' / 'Deploy Staging' 显示名的部分，PR merge 后另外 multica agent update 同步。 不在本 PR 范围。
255 lines
11 KiB
Markdown
255 lines
11 KiB
Markdown
# 开发流程（迁移到 GitHub 后）
|
||
|
||
> 适用：`github.com/TawCorp/hifast-server`（canonical 仓库）及配套的 Multica agent 工作区。
|
||
> 历史背景：本仓库于 2026-06-03 从 `git.kxsw.us/HI-VPN/hi-server` 迁移到 GitHub。**`git.kxsw.us` 已废弃**，所有新开发只走本仓库。
|
||
|
||
---
|
||
|
||
## 0. TL;DR
|
||
|
||
```
|
||
Multica issue → 分支 fix/<num>-中文简述 → 推 github → 开 PR → CI 绿 → 架构师 approve
|
||
→ GitHub UI Squash and merge 进 internal → 测试环境部署 (deploy-staging.yml) 自动跑
|
||
→ QA 在 staging 验收 → Multica issue → done
|
||
|
||
发版时：架构师把 internal squash 进 main → 对外正式版本
|
||
```
|
||
|
||
不要在 GitHub UI 之外 squash 后直接 push `internal` / `main`。不要往 `git.kxsw.us` 推。
|
||
|
||
---
|
||
|
||
## 1. 分支模型
|
||
|
||
| 分支 | 角色 | 写入方式 |
|
||
|---|---|---|
|
||
| `main` | 对外正式版本（生产） | **只**由架构师 squash merge `internal` → `main` |
|
||
| `internal` | 日常开发主干，staging 触发分支 | **只**由架构师在 GitHub UI 上 Squash and merge PR |
|
||
| `fix/<num>-…` | bug 修复分支 | 工程师自己开自己删（PR 合并后 GitHub 自动删） |
|
||
| `feat/<num>-…` | 新功能分支 | 同上 |
|
||
| `chore/…` `refactor/…` `hotfix/…` | 杂项 / 重构 / 紧急修复 | 同上 |
|
||
|
||
**分支命名约定**（严格遵守，便于 CI / CODEOWNERS / 历史追溯）：
|
||
|
||
| 前缀 | 用途 | 示例 |
|
||
|---|---|---|
|
||
| `fix/<num>-` | 关联 Multica issue 编号的 bug 修复 | `fix/143-邀请权益单测flake` |
|
||
| `feat/<num>-` | 关联 Multica issue 编号的新功能 | `feat/77-套餐列表促销信息` |
|
||
| `chore/` | 配置 / 文档 / 工具链（无关联 issue 可不带编号） | `chore/dev-workflow-docs` |
|
||
| `hotfix/<num>-` | 生产紧急修复 | `hotfix/151-payment-callback-503` |
|
||
| `refactor/<num>-` | 重构（行为不变） | `refactor/138-promo-eligibility` |
|
||
|
||
**单分支存活上限：3 天**（架构师 CLAUDE.md 约定）。超时未合并的分支由架构师在 issue 上 ping 持有者收尾或重切。
|
||
|
||
---
|
||
|
||
## 2. 标准 PR 生命周期
|
||
|
||
### 2.1 立项
|
||
|
||
- Multica 上有对应 issue（HIF-XXX）。
|
||
- issue 已 assigned，状态 `todo` 或 `in_progress`。
|
||
|
||
### 2.2 写代码
|
||
|
||
```bash
|
||
# 在 worktree 里
|
||
git fetch origin
|
||
git checkout -B fix/<num>-中文简述 origin/internal
|
||
|
||
# 编码 + 写测试
|
||
# lefthook pre-commit 会自动跑 fmt / imports / lint / vet / test
|
||
git commit -m "修复(#<num>): 一句话说清楚做了什么"
|
||
|
||
# 推到 github（不再推 git.kxsw.us）
|
||
git push origin fix/<num>-中文简述
|
||
```
|
||
|
||
**commit message**（commitlint 强制）：
|
||
|
||
```
|
||
<类型>(#<num>): <一句话描述，<= 72 字符>
|
||
|
||
<可选正文，说明 why>
|
||
```
|
||
|
||
类型只有这五个：**`修复` / `新功能` / `重构` / `文档` / `配置`**。其它一律不允许。
|
||
|
||
### 2.3 开 PR
|
||
|
||
```bash
|
||
gh pr create --base internal --title '修复(#<num>): ...' --body-file <path>
|
||
```
|
||
|
||
或 GitHub UI 开。PR 模板（`.github/PULL_REQUEST_TEMPLATE.md`）会自动填入，按指引补内容。
|
||
|
||
**PR 标题必须等于 squash 后的合入 commit 标题**（用 `<类型>(#<num>): ...` 形式）。
|
||
|
||
### 2.4 CI 自动跑
|
||
|
||
`.github/workflows/ci.yml` 在 PR 上触发：
|
||
|
||
| Job | 执行 |
|
||
|---|---|
|
||
| `build-and-test` | `go build ./...` + `go vet ./...` + `go test -race -count=1 ./...` |
|
||
| `lint` | `golangci-lint run` |
|
||
|
||
红 → 工程师本地复现 + 修，反复直到全绿。
|
||
|
||
### 2.5 Code review
|
||
|
||
- `CODEOWNERS` 自动 request review。
|
||
- 架构师（或被指派的 reviewer）逐 hunk 看，特别关注：
|
||
- scope 与 issue 一致性（无 scope creep——架构师红线之一）
|
||
- 错误处理 / SQL 注入 / N+1
|
||
- 测试覆盖关键边界
|
||
- 是否引入了无关的代码改动（架构师红线："发现成员修改了无关代码 → 立即打回重做"）
|
||
- review 通过即在 PR 上点 Approve。
|
||
|
||
### 2.6 Merge to `internal`
|
||
|
||
- **必须用 GitHub UI 的 "Squash and merge"**。
|
||
- squash 后 commit message 由架构师编辑确认：保持 `<类型>(#<num>): ...` 形式 + 必要正文。
|
||
- 合并按钮按下后 PR 自动 close，分支由 GitHub 自动删（"Automatically delete head branches" 应开启）。
|
||
- 架构师在 Multica issue 上 `@运维工程师` 附 commit hash，通知可以部署（虽然测试环境部署 workflow 已自动跑，但运维需要确认部署状态）。
|
||
|
||
**禁止做的事**：
|
||
- ❌ 在本地 squash 再 `git push` 到 `internal` / `main`
|
||
- ❌ Rebase merge / Create a merge commit（保持 linear history）
|
||
- ❌ Force push 到 `internal` / `main`
|
||
- ❌ Bypass CI（CI 红时不要 merge）
|
||
- ❌ 自己 approve 自己的 PR
|
||
- ❌ 未经测试工程师验收的分支合并（架构师红线）
|
||
|
||
### 2.7 测试环境部署自动触发 (`.github/workflows/deploy-staging.yml`)
|
||
|
||
合并到 `internal` 后，`.github/workflows/deploy-staging.yml` 自动触发：
|
||
|
||
1. `go test ./...`（已被 CI 保证过，理论上不会再红）
|
||
2. Build Docker image `registry.kxsw.us/vpn-server:<sha>` + `:staging`
|
||
3. scp `docker-compose.cloud.yml` 到 staging host
|
||
4. ssh 重启 `ppanel-server` 服务
|
||
5. healthcheck + Telegram 通知
|
||
|
||
部署失败 → Telegram 告警 → 运维介入回滚。Deploy 不阻塞下一个 PR，但**修复 deploy 是当前 deploy 失败者的责任**。
|
||
|
||
### 2.8 QA 验收
|
||
|
||
- 测试工程师在 staging（`tapi.hifast.biz` / 配套前端）按 issue 描述的 acceptance criteria 验收。
|
||
- 验收通过 → Multica issue 推 `done`。
|
||
- 任何一项失败 → 单独开子 issue 指派对应工程师，**不要**回退 PR / revert（除非生产数据安全风险）。
|
||
|
||
### 2.9 发版到 `main`（对外正式版本）
|
||
|
||
由架构师在合适的时机（feature 集齐、staging 跑稳一段时间后）执行：
|
||
|
||
```bash
|
||
gh pr create --base main --head internal --title '发版: <版本号>'
|
||
```
|
||
|
||
走和普通 PR 一样的流程（CI 绿 + review + Squash and merge）。`main` 的 push 也可以触发后续生产部署 workflow（如未来增加 `deploy-production.yml`）。
|
||
|
||
---
|
||
|
||
## 3. Multica issue 状态映射
|
||
|
||
| Multica 状态 | 对应阶段 |
|
||
|---|---|
|
||
| `backlog` | 还没排期 |
|
||
| `todo` | 已排期，待 assigned agent 开始 |
|
||
| `in_progress` | 分支已开始写，未 push |
|
||
| `in_review` | PR 已开，等 review / CI / merge |
|
||
| `done` | PR merged + 测试环境部署通过 + QA 验收通过 |
|
||
|
||
**三个条件没全满足就不要标 done**——否则验收链路看不到真问题。
|
||
|
||
Issue metadata 建议字段（与现有 agent CLAUDE.md 推荐一致）：
|
||
|
||
| 字段 | 内容 |
|
||
|---|---|
|
||
| `pr_url` | https://github.com/TawCorp/hifast-server/pull/XX |
|
||
| `merge_commit` | merge 后的 squash commit SHA |
|
||
| `deploy_url` | `tapi.hifast.biz` 或对应前端域名 |
|
||
| `pipeline_status` | `coding` / `pr_open` / `merged` / `deployed` / `qa_passed` |
|
||
| `waiting_on` | 当前阻塞点（如 `qa_e2e_access` / `architect_review`） |
|
||
|
||
---
|
||
|
||
## 4. Agent 边界
|
||
|
||
| Agent | 可以做 | 不可以做 |
|
||
|---|---|---|
|
||
| 后端 / 前端 / 运维工程师 | push 自己的 fix/feat 分支；开 PR；回评 issue；本地 squash 自己分支 | 合 PR；push `internal` / `main`；改 CODEOWNERS；自己 approve 自己 PR |
|
||
| 架构师（Squad Leader） | review；approve；GitHub UI squash merge；在 issue 上拆解需求 + 分派子任务；维护 doc/ 和 CLAUDE.md | 在本地 merge 后 push `internal`（绕过 CI gate）；直接编写业务逻辑或 UI 代码 |
|
||
| 测试工程师 | 在 staging 验收；回评 issue；开子 issue 报 bug | 改 prod 代码；改 CI workflow；自己合 PR |
|
||
| 仓库 owner（人类） | 任何越界操作 + 流程治理决策（如 branch protection 升级） | — |
|
||
|
||
任何越界都需要在 issue 上声明 + 走另一个 PR。
|
||
|
||
---
|
||
|
||
## 5. 平台层约束的现状（重要）
|
||
|
||
> 私有仓库 + 当前 GitHub plan 不支持 branch protection / rulesets API（HTTP 403）。
|
||
|
||
这意味着 "禁止直接 push internal" / "require CI pass" / "require approval" 这些**在 GitHub 平台层面没法硬强制**。当前依赖三层软约束：
|
||
|
||
1. **客户端层**：`lefthook.yml` 的 `pre-push` 钩子会在尝试直接 push `internal` / `main` 时报错。绕过去要明确加 `--no-verify`，会留 git trailers。
|
||
2. **流程层**：本文档 + `CODEOWNERS` 自动 request review + 架构师作为单一合并执行人。
|
||
3. **审计层**：所有 merge 都对应 Multica issue，事后任何"非 PR 路径上去的 commit"都能在 git log + Multica 对照查出来。
|
||
|
||
如果未来组织规模扩大、人类协作者增多，建议升级 GitHub Team（$4/user/月）拿到 branch protection 平台保障。**目前规模下软约束足够。**
|
||
|
||
---
|
||
|
||
## 6. 常见场景
|
||
|
||
### Hotfix（生产紧急修复）
|
||
|
||
走和 fix 同样的流程，只是分支前缀 `hotfix/`，PR 标题前加 `[HOTFIX]`。架构师可酌情把 review 等待时间压缩到 30 分钟以内。Hotfix 通常直接合 `internal` 后立即由架构师再开 `internal → main` 的 PR 一起发版。
|
||
|
||
### Revert
|
||
|
||
- 在 GitHub UI 上找到要 revert 的 PR，点 "Revert"。
|
||
- GitHub 会生成 revert PR，按正常流程过 review + merge。
|
||
- Revert PR 标题用 `修复(#<原 issue 编号>): revert <原 PR 标题>`。
|
||
|
||
### 文档 / 配置改动
|
||
|
||
走 `chore/` 分支。CI 一样跑（保险），review 可走 fast-track。
|
||
|
||
### 跨多个 issue 的大改动
|
||
|
||
- 优先拆成多个独立 PR，每个 PR 对应一个 issue。
|
||
- 如果实在拆不开，PR title 用 `<类型>(#XXX/#YYY/#ZZZ): ...`，PR body 里 `Closes` 三个。
|
||
|
||
---
|
||
|
||
## 7. FAQ
|
||
|
||
**Q: 为什么不允许在本地 squash 再推 internal？**
|
||
A: 绕过 GitHub PR review 流程 + CI gate + 审计记录。即使你确定改动 100% 正确，也走 PR——这是文化约束，避免架构师红线被逐渐侵蚀。
|
||
|
||
**Q: CI 跑得慢，PR 一直 yellow，可以先 merge 吗？**
|
||
A: 不可以。CI 通常 5 分钟内出结果；如果超过 15 分钟仍 pending，检查是否有 stuck job，必要时 re-run。
|
||
|
||
**Q: 如果架构师不在，怎么办？**
|
||
A: 备份 reviewer = 仓库 owner（@shanshanzhong147）。CODEOWNERS 已经把 owner 列为兜底 reviewer。
|
||
|
||
**Q: lefthook pre-push 不让我 push internal，但我确实需要紧急修一行小字？**
|
||
A: 没有"紧急修一行小字"这种例外。开 hotfix 分支 + 开 PR + 走 fast-track review。
|
||
|
||
**Q: Multica issue 状态没流转到 done，是不是要手动推？**
|
||
A: 不要直接推。先确认 PR merged + deploy 绿 + QA 通过三个条件全满足。任一项没满足就维持 `in_review` 并加评论说卡在哪。
|
||
|
||
**Q: 我能不能用 Rebase / Merge commit 模式合 PR？**
|
||
A: 不行。必须用 Squash and merge。`internal` 必须保持 linear history（一个 PR = 一个 commit），方便回滚和审计。
|
||
|
||
---
|
||
|
||
## 8. 紧急联系
|
||
|
||
- Deploy 红 / staging 挂：运维工程师（Multica agent `071d94d9-38bb-43cc-8c58-29e3b52d7bd4`）
|
||
- 流程问题 / branch protection 决策：仓库 owner @shanshanzhong147
|
||
- 架构 / API 设计：架构师（Multica agent `0de10589-f101-49ef-8dfa-0e9e992fe27c`）
|