SpecSure 项目分支管理办法

分支管理办法

在和队友一起做 SpecSure 这个项目的过程中，我一开始就发现：如果分支和目录的概念不统一，协作会很快变乱。所以在项目早期，我花了一点时间把分支管理方式梳理清楚。

这篇文章主要记录我自己的理解和实践经验，给之后做类似项目的自己，也给可能遇到同样问题的同学一个参考。

---

0. 先把一个常见误区说清楚：分支 ≠ 目录

刚开始合作时，大家很容易把分支当成目录来理解，但这两者其实解决的是完全不同的问题。

• 目录（folder） 是用来区分项目内容的，比如前端、后端、模型、文档：
  • frontend/
  • backend/
  • models/
  • docs/
• 分支（branch） 则是整个项目在某一时刻的“快照”，是一条完整的时间线
  • 不管在哪个分支，目录结构都是完整的一套，只是代码版本不同

一旦这点想清楚，后面的分支设计就顺很多。

---

1. 整体分支方案

只保留 1 个长期稳定分支：main

• main = 任何时候都能完整跑通的版本
• 用于答辩、演示、阶段性展示
• 不允许把明显跑不起来的代码直接丢进 main

换句话说，main 更像是项目的“对外展示窗口”。

---

其他分支全部作为临时工作分支

除了 main，其他分支都只是为了方便开发和协作存在的。我直接按大家的主要工作内容来命名：

• feature-frontend —— 前端页面开发
• feature-backend —— 后端 API 和数据处理
• feature-svm —— 模型 A：SVM
• feature-cnn —— 模型 B：3D CNN

但也提醒大家：分支是分工，不是隔离，每个人都要对整体结构有基本理解。

---

2. 我们是怎么实际使用分支的？

第一步：所有人都从 main 开始

不管是谁，刚开始一定是从 main 拉代码，这样大家的基础环境是一致的：

git clone https://github.com/<你的用户名>/SpecSure.git
cd SpecSure
git checkout main

---

第二步：根据自己负责的模块新建分支

比如负责前端的同学就要这样做：

git checkout -b feature-frontend
git push -u origin feature-frontend

做 SVM 的同学就对应：

git checkout -b feature-svm
git push -u origin feature-svm

一个基本原则是：日常开发只在自己的 feature 分支上进行，不直接改 main。

---

3. 日常开发时的分支流程

这里以在 feature-frontend 上开发为例。

① 写代码前，先同步一次 main

这是我后来觉得最重要的一步，能避免很多冲突：

git checkout main
git pull origin main        # 拿到最新的稳定版本
git checkout feature-frontend
git merge main              # 把 main 的更新合进来

这样写代码时，基础版本始终是最新的。

---

② 完成一个阶段功能后，提交到自己的分支

git add .
git commit -m "frontend: 完成数据导入页面初版"
git push origin feature-frontend

这里我会尽量让每次提交都“有意义”，而不是一堆零碎改动。

---

③ 功能稳定后，通过 PR 合并回 main

当我觉得某个功能已经可以作为项目的一部分时，就会发一个 PR：

1. 在 GitHub 上点击 Compare & pull request
2. 确认方向是
   base: main ← compare: feature-frontend
3. 写清楚：
   • 改了什么
   • 怎么运行
   • 有没有需要注意的地方
4. 请一个队友帮忙看一眼再合并

合并完成后，main 就会变成新的“完整可运行版本”。

如果这个分支后续不再需要，也可以直接删掉；留着也不会有问题。

---

4. 为什么坚持所有分支目录结构一致？

不管是在 main，还是在 feature-svm、feature-cnn，我都要求目录结构保持一致：

• 做前端 → 主要改 frontend/，但依然是在 feature-frontend 分支
• 做 SVM → 改 models/ 和部分后端接口，在 feature-svm 分支
• 文档更新 → 改 docs/，单独开 feature-docs

分支负责“谁在改”，目录负责“改哪里”，两者分工清晰，协作成本会低很多。

---

写在最后

这套分支管理方式并不复杂，但对我们这种课程项目来说，已经足够稳定、清晰、好维护。

对我个人来说，它的价值在于：

• 减少互相覆盖代码的风险
• 保证随时有一个能跑的版本
• 让每个人都能安心在自己的任务线上推进

如果之后再做类似的项目，我大概率还会沿用这一套思路。