master/main 分支必须保持可部署状态，禁止直接推送，需通过分支保护规则强制代码审查、ci 流水线验证；develop 是日常开发唯一上游，所有功能从其拉取 feature 分支并以 pr 合入；feature 分支须命名规范、生命周期受控、单一职责；合并前须本地运行测试、同步配置、更新 changelog。
master/main 分支必须保持可部署状态
它不是“开发完成才合并”的终点，而是随时能打 tag、上线的稳定基线。任何直接向 master 或 main 的推送（git push origin master）都应被禁止——哪怕你只是改了个 README。
实际操作中，团队必须启用分支保护规则（GitHub/GitLab 的 Branch Protection Rules），强制要求：
-
push权限仅开放给 CI/CD 系统或运维角色 - 合并前必须通过至少 1 个代码审查（PR review）
- 必须通过指定的 CI 流水线（如单元测试、构建、安全扫描）
- 禁止直接
force-push到该分支
如果某次 hotfix 合并后发现线上异常，回滚最快的方式是 git revert -m 1 <merge-commit-hash></merge-commit-hash>，而不是删掉提交历史——后者会破坏所有基于该 commit 的后续分支。
develop 分支是日常开发的唯一上游
所有新功能、优化、非紧急修复，都必须从 develop 拉出 feature 分支，开发完再以 PR 方式合入 develop。它不是“随便提交”的中转站，而是下一版发布的预集成环境。
关键维护动作包括：
- 每天至少一次同步：在本地
develop上执行git pull --rebase origin develop，避免本地产生无意义的 merge commit - 每周清理已合并的 feature 分支：
git branch --merged develop | grep -v "develop\|master\|main" | xargs git branch -d - 若
develop出现长期未修复的 CI 失败，必须暂停新 PR 合并，优先修复构建链路——否则它会迅速退化为“不可信分支”
注意：develop 上不应存在未测试的、半成品的提交。它的每次更新，都应对应一次可验证的集成结果。
feature 分支命名与生命周期管理
命名不是为了好看，而是为了快速定位上下文。推荐格式：feature/user-login-v2、refactor/api-client、chore/ci-add-python311。开头用短横分隔类型和主题，避免空格、下划线、中文。
生命周期必须受控：
- 创建时明确 base 分支：
git checkout -b feature/search-cache develop（不是master，也不是当前所在分支） - 每日至少一次同步 base：
git rebase develop（不是merge develop），保持线性历史且减少冲突范围 - 超过 7 天未更新的分支，CI 应自动标记为 stale；超过 14 天未更新且未关联 Jira/TAPD 卡片的，应由仓库管理员归档或删除
一个常见错误是把多个不相关改动塞进同一个 feature/xxx 分支——这会让 PR 审查失效，也阻碍部分功能提前合入。拆分原则很简单：一个分支只解决一个问题，且能独立测试。
合并到 develop 前必须做三件事
不是点下 Merge 按钮就完事。真正决定质量的是合并前的检查项：
- 本地运行全部单元测试：
pytest tests/或go test ./...，确保覆盖率没下降 - 检查是否遗漏了新配置项：比如新增了
config.yaml字段，但没在 CI 的 config template 中同步 - 确认日志/错误码/HTTP 状态码变更已记录在 CHANGELOG.md 对应条目下（哪怕只是内部项目）
最容易被跳过的，是第三项。没有变更记录，下次排查线上 500 错误时，你就得翻几十个 commit 找谁改了 status code。这不是仪式感，是故障响应的第一公里。
