WenZhenGuardian 团队开发规范

Created on December 04, 2025

2025   ·   team   workflow   ·   notes

WenZhenGuardian 团队开发规范 一、分支规范 ✔ 默认分支

main：稳定版本，只存放已测试、可部署代码 ⚠ 禁止直接在 main 上开发

✔ 开发分支

每个成员开发功能必须新建功能分支：

feature/<功能名> bugfix/<修复内容> hotfix/<紧急修复> refactor/<重构内容>重构内容>紧急修复>修复内容>功能名>

示例：

✔ 2. 加入 GitHub Actions

WenZhenGuardian 团队开发规范

一、分支规范

  • 默认分支
    • main：稳定版本，只存放已测试、可部署代码
    • ⚠️ 禁止直接在 main 上开发
  • 开发分支（每个成员必须新建）
    • feature/<功能名>
    • bugfix/<修复内容>
    • hotfix/<紧急修复>
    • refactor/<重构内容>

WenZhenGuardian 团队开发规范（详尽版）

目的：统一团队协作流程，减少合并冲突，提高代码质量与交付效率。优先保证 main 分支始终可部署。

一、分支规范（详尽）（bushi）（不详尽）

总体原则：

  • 保持 main（或 release）为稳定、可部署分支；所有开发活动在临时分支完成并通过 PR 合并。
  • 分支命名应可读、可追溯、短小且语义化，便于审查和 CI 跟踪。
  • 说人话就是，大家千万不要懂main分支
  • 然后可以看看如何创建新分支，每个人有自己的分支

推荐分支类型与用途：

  • main：生产/部署分支，仅可通过合并 PR 更新（受分支保护策略管控）。
  • develop（可选）：汇总短期开发成果的集成分支；团队较大或需要持续集成时建议使用。若使用此分支，Feature 分支应合并到 develop，release 从 develop 发出并合并回 main 与 develop。
  • feature/<短描述>：新功能分支，仅包含一个明确的功能点或任务（如 feature/login-oauth）。
  • bugfix/<短描述>：用于修复开发中发现但不紧急的问题（合并到 develop 或 main 视流程而定）。
  • hotfix/<短描述>：用于线上紧急问题，直接从 main 创建，修复后需合并回 main 和 develop（若存在）。
  • release/<x.y.z>（可选）：准备发布的分支，用于最后的集成测试与版本号调整，测试通过后合并回 main 并打 tag。
  • refactor/<短描述>：仅用于重构，要求在 PR 中说明不改变外部行为。

分支命名规范（示例）：

feature/auth-jwt
bugfix/login-redirect
hotfix/critical-500
refactor/api-client
release/1.2.0

常见操作命令（示例）：

# 从远程更新本地 main
git checkout main
git pull origin main

# 创建 feature 分支
git checkout -b feature/auth-jwt

# 在分支上工作、提交、推送
git add .
git commit -m "feat(auth): add JWT login"
git push -u origin feature/auth-jwt

PR 与合并策略：

合并到main分支必须经过bosprimigenious审核

  • 所有分支合并到 main（或 develop）必须通过 Pull Request。PR 要求至少一个代码评审者通过（人数可在分支保护中设置）。
  • CI 必须通过（lint/format/tests）才能合并。
  • 合并方式建议：
    • 对于保留历史：使用 Merge commit（默认），有利于保留上下文；
    • 对于整洁历史：可使用 Squash and merge，把多次提交合并为一次有意义提交；
    • 不建议在公共分支上强制 rebase，以避免复杂的历史重写风险。

冲突处理（简单流程）：

  1. 拉取远端最新目标分支：git fetch origin，切换目标分支并 git pull。
  2. 在自己的分支执行 git merge origin/main（或 origin/develop），解决冲突并 git add 冲突文件。
  3. git commit（必要时），再 git push 到远程分支，PR 会自动更新。

示例：从 main 合并到 feature 并解决冲突：

git checkout feature/auth-jwt
git fetch origin
git merge origin/main
# 解决冲突后
git add conflicted_file.py
git commit -m "fix: resolve merge conflicts with main"
git push

分支生命周期建议：

  • Feature 分支：短生命周期（建议不超过 2 周），长时间分支增加冲突风险。
  • Hotfix：创建后尽快修复并合并回 main 与 develop，打上补丁版本号。
  • Release：用于最终集成测试，不应在 release 分支上新增新功能。

权限与分支保护（建议在 GitHub 上配置）：

  • 对 main 启用 Branch protection：
    • 勾选：Require pull request before merging
    • 勾选：Require status checks to pass before merging（选中 CI 检查）
    • 勾选：Require approvals（最少 1 或 2 位审查者）
    • 可选：Restrict who can push to matching branches（仅允许管理员或 CI 推送）

二、提交信息（Git Commit）规范（简洁但强制）

规则：

  • 格式：<type>(<scope>): <short summary>，例如：feat(auth): add JWT login
  • 常用 type：feat、fix、docs、style、refactor、test、chore
  • 每个提交的 summary 不超过 72 个字符；需要详细描述时在 body 中说明。示例：
feat(auth): add JWT login

- 支持 access/refresh token
- 增加 token 刷新路由

Git 提交示例命令：

git add changed_file.py
git commit -m "feat(api): add inference endpoint"

三、Pull Request（PR）模板与评审要点

在仓库中添加 .github/PULL_REQUEST_TEMPLATE.md 可强制 PR 填写必要信息。建议内容：

  • 概述：做了什么？
  • 变更类型：feat/fix/docs/chore 等
  • 为何需要：问题背景或需求来源
  • 如何测试：复现步骤、测试用例或截图
  • 关联 issue：若有关联 issue 请列出

评审要点清单：

  • 功能实现是否完整（边界/错误处理）
  • 测试覆盖是否充足（unit/integration）
  • 代码是否风格一致并通过 lint
  • 是否存在性能/安全隐患
  • 文档/注释是否更新

四、CI 与自动化建议（概要）这个我自己也没懂，其实，还在学习

建议在 main/develop 的 PR 检查中加入以下 CI：

  • 代码风格：black（Python）、Prettier（JS）
  • 静态检查：flake8（Python）、ESLint（JS）
  • 测试：单元测试、关键集成测试
  • 构建或类型检查：mypy（可选）、tsc（如使用 TS）

可用动作：.github/workflows/ci.yml 配置自动在每个 PR 运行上述检查并把结果作为合并前必须通过的状态检查。

五、分支与版本管理实战示例（完整流程）

场景：你完成了登录功能，需要把它合并到主线并发布到测试环境。

流程：

  1. 本地创建 feature 分支并开发：
git checkout -b feature/login-oauth
# 开发、提交多次
git push -u origin feature/login-oauth

  1. 打开 GitHub 创建 PR（目标分支 develop 或 main），填写 PR 模板。

  2. CI 运行，审查者 review 并提出修改意见 → 按照建议修复并 push。

  3. CI 全部通过并获得审批，合并方式选择 Squash and merge（使历史清晰）。

  4. 若合并到 main，在合并后打 tag 发布：

git checkout main
git pull origin main
git tag -a v1.2.0 -m "Release v1.2.0"
git push origin v1.2.0
  1. 若使用 develop，请确保把变更合并回 main（并发 release 流程）。

六、最佳实践与常见问题

  • 保持分支短小，频繁与主线同步，减少冲突成本。
  • 每次 PR 聚焦单一目的（Bug 修复、一个 feature、重构），避免“大而全”的 PR。
  • 对二进制/大文件使用 Git LFS 或将其置于模型仓库/对象存储，不要直接放到 Git 仓库中。
  • 对数据与模型（>100MB）使用外部存储，并在仓库中提供下载脚本或配置说明。

常见问题：

  • Q：合并冲突太多怎么办？
    • A：把主线改动拉到本地分支（git merge origin/main），按文件逐一解决，鼓励小步提交与更频繁的合并。
  • Q：谁可以合并 PR？
    • A：通过分支保护设置（Require approvals）来限制，通常要求至少一位有写权限的 reviewer 批准。

七、附：常用 Git 命令速查表

# 克隆
git clone <repo>

# 查看远程
git remote -v

# 创建并切换分支
git checkout -b feature/xxx

# 提交
git add .
git commit -m "feat: ..."

# 推送分支
git push -u origin feature/xxx

# 合并远端 main 到当前分支
git fetch origin
git merge origin/main

# 删除远端分支
git push origin --delete feature/old
  • 剩下的看看git使用指南+配套大模型问问得了，够用了。


Enjoy Reading This Article?

Here are some more articles you might like to read next: