跳转至

TWS 项目 Git 分支策略

分支模型

1
2
3
4
5
6
7
8
main ──┬── v0.1 ── v0.2 ── v0.3 ── ...
       │
       └── develop ─────────────────
            │
            ├── feat-firmware-ble
            ├── feat-firmware-anc
            ├── feat-hw-schematic
            └── fix-xxx

分支说明

分支 用途 保护规则
main 稳定发布版本 PR 必须经过 review + CI 通过
develop 日常开发集成分支 所有 feat-* 合入此分支
feat-* 功能开发分支 从 develop 切出，完成后 PR → develop
fix-* Bug 修复分支 可从 develop 或 main 切出
refs/ 外部参考代码（不参与构建） 不合并

提交信息规范

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
<type>(<scope>): <description>

类型:
  feat     — 新功能
  fix      — Bug 修复
  docs     — 文档更新
  test     — 测试补充/修改
  chore    — 构建/工具链/CI
  refactor — 重构
  hw       — PCB/硬件设计变更

scope:
  fw       — firmware/
  hw       — pcb/ + docs/hardware/
  test     — tests/
  docs     — docs/ (非 hardware)
  ci       — .github/ + scripts/
  task     — tasks/

示例:
  feat(fw): 实现 BLE GATT 电池服务
  fix(hw): 修正麦克风偏置电路电容值
  test(fw): 增加配对超时重试测试
  docs(fw): 更新串口命令表
  chore(ci): 添加 GitHub Actions 工作流

工作流

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
# 1. 从 develop 创建功能分支
git checkout develop
git checkout -b feat-firmware-ble

# 2. 开发 + 提交
git add firmware/src/ble.c
git commit -m "feat(fw): 实现 BLE 广播和连接"

# 3. 同步 develop
git fetch origin
git rebase origin/develop

# 4. 推送并创建 PR
git push origin feat-firmware-ble
# 在 GitHub/Gitea 创建 PR → develop

# 5. 发布时合并到 main
git checkout main
git merge --no-ff develop
git tag v0.1.0

CI/CD 流水线

每次 push 到 main/develop/feat-* 自动运行： 1. ✅ make check — 固件语法检查 2. ✅ make run — 主机单元测试 3. ✅ Clang-format — 代码风格 4. ✅ Markdownlint — 文档格式 5. ✅ 任务文件有效性检查

推送指引

首次推送： 

1
2
3
4
5
6
7
# 创建 GitHub 仓库后
git remote add origin https://github.com/<user>/tws-earbuds.git
git push -u origin main

# 推送 develop 分支
git branch develop main
git push -u origin develop