247 lines
5.4 KiB
Markdown
247 lines
5.4 KiB
Markdown
# 05 — Git 协作规则
|
||
|
||
> **适用**：所有 AI 和人工开发任务。分支怎么拉、什么时候合、冲突怎么处理。
|
||
|
||
---
|
||
|
||
## 分支模型
|
||
|
||
```
|
||
master ──────────────────────────────────────────→ 生产
|
||
│
|
||
└── test ──────────────────────────────────────→ 测试主线
|
||
└── dev ──────────────────────────────────────→ 开发主线
|
||
│
|
||
├── feature/任务编号-简短描述 → 新功能
|
||
├── bugfix/任务编号-简短描述 → Bug修复
|
||
└── hotfix/任务编号-简短描述 (从 master 拉) → 紧急修复
|
||
```
|
||
|
||
### 什么时候从哪拉
|
||
|
||
| 场景 | 从哪拉 | 合回哪 |
|
||
|------|--------|--------|
|
||
| 新功能 | `dev` | `dev` |
|
||
| Bug 修复 | `dev` | `dev` |
|
||
| 紧急线上修复 | `master` | `master` + `dev`（两边都要合） |
|
||
|
||
### 分支命名
|
||
|
||
```
|
||
feature/2688-用户批量导入 ← 禅道任务号 + 功能描述
|
||
bugfix/2690-任务列表分页错误
|
||
hotfix/2691-登录验证码绕过
|
||
|
||
禁止：
|
||
feature/xxx ← 没任务号
|
||
zhangsan-test ← 没意义
|
||
dev-backup-20260603 ← 备份不是分支
|
||
```
|
||
|
||
---
|
||
|
||
## 日常操作
|
||
|
||
### 开始一个新任务
|
||
|
||
```bash
|
||
# 1. 切到 dev，拉最新
|
||
git checkout dev
|
||
git pull origin dev
|
||
|
||
# 2. 从 dev 拉分支
|
||
git checkout -b feature/任务号-功能描述
|
||
|
||
# 3. 开发...
|
||
|
||
# 4. 定期提交（不要攒到最后一次性交）
|
||
git add .
|
||
git commit -m "feat: xxx"
|
||
|
||
# 5. 推送到远程（每天至少推一次，防止本地丢失）
|
||
git push origin feature/任务号-功能描述
|
||
```
|
||
|
||
### 合并回 dev
|
||
|
||
```bash
|
||
# 1. 确保本地 dev 最新
|
||
git checkout dev
|
||
git pull origin dev
|
||
|
||
# 2. 切回自己的分支，rebase dev（让历史干净）
|
||
git checkout feature/任务号-功能描述
|
||
git rebase dev
|
||
|
||
# 如果有冲突：
|
||
# - 逐个文件解决冲突
|
||
# - git add <解决的文件>
|
||
# - git rebase --continue
|
||
# - 直到完成
|
||
|
||
# 3. 推 rebase 后的分支（需要 --force-with-lease，不是 --force）
|
||
git push --force-with-lease origin feature/任务号-功能描述
|
||
|
||
# 4. 到 Git 平台提 PR/MR 到 dev
|
||
# PR 标题：feat: 用户管理增加批量导入
|
||
# PR 描述：改了什么、怎么测试
|
||
```
|
||
|
||
### 冲突处理
|
||
|
||
```
|
||
1. git status 看哪些文件冲突
|
||
2. 打开冲突文件，找到 <<<<<<< ======= >>>>>>> 标记
|
||
3. 逐行确认保留哪边的代码
|
||
4. 删掉标记符号
|
||
5. git add <文件>
|
||
6. git rebase --continue 或 git merge --continue
|
||
7. 编译验证
|
||
```
|
||
|
||
**常见错误**：看到冲突整块接受一边，把别人的代码覆盖了。必须逐行看。
|
||
|
||
---
|
||
|
||
## AI 开发特殊规则
|
||
|
||
### AI 提交必须标注
|
||
|
||
```
|
||
feat: 用户管理增加批量导入 [AI: Claude Code]
|
||
|
||
- 新增 UserBatchImportController
|
||
- 新增 UserImportService
|
||
- 新增 import_batch 表
|
||
- 前端增加导入按钮和上传弹窗
|
||
```
|
||
|
||
**为什么**：review 时知道这是 AI 写的，检查更仔细（尤其是边界条件和安全性）。
|
||
|
||
### AI 解决冲突
|
||
|
||
AI 遇到冲突时，不能自己决定保留哪边。必须：
|
||
1. 列出冲突内容和两边来源
|
||
2. 让人类决定
|
||
3. 人类确认后再继续
|
||
|
||
### AI 禁止操作
|
||
|
||
```bash
|
||
# ❌ AI 绝对禁止
|
||
git push --force origin dev # 强制推共享分支
|
||
git push --force origin master # 同上
|
||
git reset --hard HEAD~10 && git push -f # 回退远程历史
|
||
git commit --amend && git push -f # 修改已推送的 commit
|
||
```
|
||
|
||
---
|
||
|
||
## Commit 格式
|
||
|
||
```
|
||
<type>: <简短描述> [来源标注]
|
||
|
||
类型：
|
||
feat: 新功能
|
||
fix: Bug 修复
|
||
refactor: 重构（不改功能）
|
||
style: 格式调整
|
||
docs: 文档
|
||
test: 测试
|
||
chore: 构建/依赖/工具
|
||
|
||
来源标注（AI 写的必须加）：
|
||
[AI: Claude Code]
|
||
[AI: Kimi]
|
||
[AI: Codex]
|
||
|
||
正确示例：
|
||
feat: 用户管理增加批量导入 [AI: Claude Code]
|
||
fix: 任务列表分页总数计算错误
|
||
refactor: 提取公共校验逻辑到 BaseService
|
||
chore: 升级 Spring Boot 到 3.5.6
|
||
|
||
禁止示例：
|
||
update ← 无意义
|
||
fix bug ← 不知道修的哪个 bug
|
||
修改 ← 中文且无具体内容
|
||
WIP / temp / test ← 临时提交应该 squash 掉
|
||
```
|
||
|
||
---
|
||
|
||
## PR / MR 规范
|
||
|
||
### PR 必须包含
|
||
|
||
```markdown
|
||
## 改了什么
|
||
简要描述改动内容
|
||
|
||
## 关联任务
|
||
禅道 #2688 / 需求文档链接
|
||
|
||
## 测试方式
|
||
- [ ] 本地编译通过
|
||
- [ ] 接口测试通过
|
||
- [ ] 前端页面正常
|
||
|
||
## 契约变更
|
||
- [ ] 无接口变更
|
||
- [ ] 有接口变更 → 已更新 contract/ 目录 → 已通知前端
|
||
```
|
||
|
||
### Review 规则
|
||
|
||
- 至少一人 approve 才能合
|
||
- AI 生成的代码必须至少一人 review
|
||
- 改动超过 500 行 → 拆分 PR
|
||
|
||
---
|
||
|
||
## .gitignore 必备
|
||
|
||
```
|
||
# Java
|
||
target/
|
||
*.class
|
||
*.jar
|
||
*.war
|
||
|
||
# IDE
|
||
.idea/
|
||
*.iml
|
||
.vscode/
|
||
.settings/
|
||
.project
|
||
.classpath
|
||
|
||
# 前端
|
||
node_modules/
|
||
dist/
|
||
.env.local
|
||
|
||
# 系统
|
||
.DS_Store
|
||
Thumbs.db
|
||
|
||
# 敏感信息
|
||
*.pem
|
||
*.key
|
||
application-prod.yml （如果有密码）
|
||
```
|
||
|
||
---
|
||
|
||
## 检查表
|
||
|
||
- [ ] 分支从正确的源头拉（功能/Bug → dev，紧急 → master）
|
||
- [ ] 分支名包含任务号
|
||
- [ ] commit message 有意义
|
||
- [ ] AI 提交标注了来源
|
||
- [ ] push 前 rebase 了 dev
|
||
- [ ] 没用 `--force` 推共享分支
|
||
- [ ] 冲突逐行解决，没整块覆盖
|
||
- [ ] PR 有描述和测试说明
|