PR 工作流

May 14, 2026 · View on GitHub

阅读本文后，你将掌握 HotPlex 的分支命名、Commit 规范、PR 创建流程和 CI 要求，能够顺利提交贡献。

概述

所有代码变更必须通过 PR 合并，不允许直接推送到 main 分支。项目遵循 Conventional Commits 规范，PR 必须通过 CI（lint + test + build）。

前提条件

步骤

1. 创建功能分支

Admin（仓库协作者）

拥有仓库 write/admin 权限的协作者直接在 origin 仓库创建分支：

# 从最新 main 创建功能分支
git fetch origin main
git checkout -b feat/<feature-name> origin/main

外部贡献者

无仓库直接权限的贡献者使用 fork-PR 工作流：

# 1. 在 GitHub 上 fork 仓库
# 2. 添加远程
git remote add fork https://github.com/<your-username>/hotplex.git

# 3. 创建功能分支（基于上游 main）
git fetch origin main
git checkout -b feat/<feature-name> origin/main

2. 分支命名规范

类型格式示例
新功能feat/<name>feat/cron-scheduler
Bug 修复fix/<name>fix/session-race
重构refactor/<name>refactor/hub-backpressure
文档docs/<name>docs/contributor-guides
杂项chore/<name>chore/update-deps

3. 开发与提交

遵循 Conventional Commits 规范：

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

类型：

类型用途
feat新功能
fixBug 修复
refactor代码重构（不改变行为）
docs文档变更
test测试相关
chore构建、依赖、工具
perf性能优化

Scope 示例：gateway、session、worker、messaging、cron、config、security、brain

示例：

feat(cron): add lifecycle limits for recurring jobs

Support --max-runs and --expires-at flags to bound job execution.
Jobs auto-disable when limits are reached.

Closes #123

4. 提交前检查

# 完整 CI 流程（推荐）
make check

make check 等效于 CI 流程：fmt → lint → test → build。

检查清单：

  • make fmt 通过
  • make lint 无新增 warning
  • make test 通过（含 race 检测）
  • make build 成功
  • 新功能有对应测试
  • Commit message 遵循 Conventional Commits

Git pre-push hook 会自动运行格式化、lint、构建和测试。如果未安装，运行 make hooks。

5. 推送并创建 PR

Admin

# 推送到 origin
git push -u origin feat/<feature-name>

# 创建 PR
gh pr create --title "feat(scope): description"

外部贡献者

# 推送到 fork
git push -u fork feat/<feature-name>

# 创建 PR（从 fork 到上游 main）
gh pr create \
  --base main \
  --head <your-username>:feat/<feature-name> \
  --title "feat(scope): description"

6. 合并后清理

# 切回 main 并拉取最新
git checkout main && git pull origin main

# 删除本地分支
git branch -d feat/<feature-name>

# 删除远程分支（Admin）
git push origin --delete feat/<feature-name>

# 外部贡献者删除 fork 上的分支
git push fork --delete feat/<feature-name>

CI 要求

所有 PR 必须通过 CI 检查：

阶段命令说明
格式化go fmt + goimports代码格式
Lintgolangci-lint run ./...静态分析
测试go test -race -timeout 15m ./...含竞态检测
构建go build编译通过

本地验证：make check 等效 CI。

验证

  • PR 在 CI 全部通过后才可合并
  • PR 标题使用 Conventional Commits 格式
  • 至少一位 reviewer approve 后方可合并

下一步