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