TTMusic/doc/Git协作规范v1.0.md

Git 协作规范 v1.0

1. 目标与适用范围

本规范用于降低 git pull 后冲突率，避免本地改动被覆盖，统一 TTMusic 项目的团队协作流程。

适用范围：所有参与本仓库开发与评审的成员。

2. 分支模型与集成规则

• 主干分支（main/master）仅用于集成，禁止直接提交。
• 功能开发使用 feature/* 分支。
• 缺陷修复使用 fix/* 分支。
• 主干合入必须通过 PR，并完成代码评审后合入。

分支命名示例：

• feature/webdav-upload-refactor
• fix/local-music-crash-on-resume

3. 日常同步 SOP

3.1 拉取前强制检查

每次 pull / rebase / 切分支前，必须执行：

git status

判定规则：

• 工作区干净：可继续同步。
• 存在未提交改动：必须先 commit 或 stash，禁止直接同步。

3.2 标准同步流程

git status
git fetch origin
git rebase origin/<base-branch>

适用边界：

• 个人分支优先使用 rebase 保持线性历史。
• 对共享分支或已公开历史，若不适合 rebase，可使用 merge，但需在 PR 说明中注明。

3.3 推送与集成检查

推送前检查：

• 提交是否按语义组织，避免把无关改动混到同一 commit。
• 是否已完成基础构建/自测。
• PR 描述是否包含：改动范围、风险点、验证结果。

4. 冲突处理 SOP

4.1 冲突定位

git status

定位含冲突文件后，逐个处理冲突标记（<<<<<<<、=======、>>>>>>>）。

4.2 手工解决与验证

• 按业务语义合并，不做机械保留。

• 解决后执行：

  git add <file>
  git rebase --continue   # 或 git commit（merge 场景）
  

• 完成后至少执行一次关键路径验证（构建/核心流程冒烟）。

4.3 提交与记录

冲突解决提交信息建议包含 conflict-resolve 关键字，并在 PR 说明中记录冲突来源与处理原则。

5. 本地改动保护与恢复 SOP

5.1 命名 stash 规范

git stash push -m "<date>-<branch>-<purpose>"

示例：2026-02-06-feature-webdav-sync-before-rebase

5.2 临时备份分支规范

git switch -c backup/<date>-<topic>

用于保护未完成改动，避免误操作覆盖。

5.3 恢复流程

git stash list
git stash apply stash@{n}

若冲突，回到“冲突处理 SOP”处理。

6. 高风险命令红线

以下命令属于高风险操作，默认禁止直接执行：

• git reset --hard
• git checkout -- <path>（覆盖工作区）
• git clean -fd

允许前置条件：

• 已创建可恢复点（commit / stash / backup 分支）。
• 明确知晓影响范围并经过二次确认。

7. 仓库基线策略

7.1 文本归一化

• 统一通过 .gitattributes 管理行尾与文本识别，避免跨平台伪冲突。

7.2 二进制与不可安全文本合并文件

• 二进制文件标记为 -text，禁止按文本方式合并。
• 对锁文件、HAR 等生成/归档文件，根据版本管理策略决定是否纳入版本库。

8. 已知限制与后续优化

已知限制：

• 团队尚未建立自动化冲突预警机制，流程依赖人工执行。
• 某些跨团队紧急变更可能临时偏离标准流程。

后续优化：

• 结合 PR 模板与 CI 检查增强流程约束。
• 统计冲突热点文件并优化模块边界。