/## Context 当前仓库在多人协作时缺少统一 Git 操作约束，开发者在 `pull`、`rebase`、`merge`、`stash` 和分支切换中的行为不一致，导致两类核心问题： - 冲突频发且处理方式不一致，重复消耗时间。 - 本地未提交改动在高风险操作中被覆盖或丢失。 本次设计需要在不改变业务运行时行为的前提下，给出可执行、可落地、可审计的协作机制，覆盖日常开发与异常处置场景。 ## Goals / Non-Goals **Goals:** - 形成统一的分支与同步策略，降低无效冲突。 - 建立 pull 前本地改动保护流程，显式避免“误覆盖”。 - 通过仓库基线配置（如 `.gitattributes`）减少跨平台伪冲突。 - 提供冲突与覆盖风险的标准化处置手册，提升团队一致性。 **Non-Goals:** - 不改动业务代码逻辑与运行时接口。 - 不引入复杂的 Git 托管平台自动化体系（如强制机器人流程改造）。 - 不在本阶段处理历史提交重写或大规模分支清理迁移。 ## Decisions 1. 采用“受保护主干 + 短生命周期功能分支”策略。 - 选择：`main/master` 仅通过 PR 合入，个人开发在 `feature/*`、`fix/*` 分支进行。 - 原因：隔离日常开发与集成风险，减少直接在主干上产生冲突。 - 备选：继续允许直接向主干提交。 - 不选原因：无法有效约束冲突来源，且回溯困难。 2. 统一日常同步基线为“先检查本地改动，再同步远端”。 - 选择：pull 前执行状态检查（`git status`），发现未提交改动时必须先 `commit` 或 `stash`。 - 原因：把风险前置，避免 merge/rebase 时混入脏工作区。 - 备选：允许直接 `git pull` 自动处理。 - 不选原因：高概率引入隐式冲突和覆盖风险。 3. 默认以 rebase 同步个人分支（保持线性历史），主干集成仍通过 PR merge 策略控制。 - 选择：开发者本地 `fetch + rebase` 为主，减少无意义 merge commit。 - 原因：冲突定位更清晰，历史可读性更高。 - 备选：全面 merge 同步。 - 不选原因：历史噪音大，冲突来源不直观。 4. 建立“本地改动保护”硬性规则。 - 选择：禁止在未理解后果时使用 `reset --hard`、`checkout -- .` 等破坏性命令；提供 stash 命名规范和恢复流程。 - 原因：覆盖问题主要来源于破坏性命令与无保护 pull。 - 备选：仅口头提醒。 - 不选原因：不可审计，执行一致性低。 5. 增加仓库冲突预防基线。 - 选择：补充 `.gitattributes`（统一文本归一化、二进制标注、必要的 merge 策略）与 `.gitignore` 建议项。 - 原因：减少跨系统换行差异和二进制误合并引发的伪冲突。 - 备选：维持默认 Git 行为。 - 不选原因：跨平台团队中冲突噪音无法下降。 6. 文档化并模板化操作流程。 - 选择：在 `doc/` 增加“日常同步 SOP”“冲突处理 SOP”“本地改动恢复 SOP”。 - 原因：将经验固化为可执行步骤，降低新人上手成本。 - 备选：分散在聊天记录或口头传递。 - 不选原因：知识不可追踪，执行偏差大。 ## Risks / Trade-offs - [Risk] 团队成员对新流程不熟悉，短期操作成本上升 -> Mitigation：提供最小命令清单与示例，PR 阶段进行轻量检查。 - [Risk] rebase 使用不当可能改写本地历史 -> Mitigation：明确“仅在个人未共享分支 rebase”的规则，并提供回滚指令。 - [Risk] `.gitattributes` 调整后可能触发一次性大 diff -> Mitigation：分阶段引入并在独立 PR 中完成，避免与业务改动混合。 - [Risk] 规则过严影响紧急修复效率 -> Mitigation：定义紧急通道，但要求事后补齐规范流程与记录。 ## Migration Plan 1. 在文档中发布新协作规范与高风险命令红线。 2. 引入 `.gitattributes`/`.gitignore` 基线变更，并单独评审。 3. 团队试运行 1-2 个迭代，收集冲突率与恢复案例。 4. 根据试运行反馈调整 SOP 细节。 5. 将规范纳入 PR 模板或开发检查清单。 回滚策略：若新基线导致异常，可先回退文档强制项与 `.gitattributes` 改动，保留最小安全规则（pull 前检查与本地改动保护）。 ## Open Questions - 是否统一要求 `pull.rebase=true`，还是按分支类型区分？ - 是否需要在仓库内提供一键安全同步脚本（如 `safe-pull`）？ - PR 模板中哪些检查项必须强制，哪些可选？ - 是否需要为二进制资源（如媒体文件）制定单独的分支与提交流程？