branch-policy

分支策略

分支模型

main        ← production. Updated ONLY by PR from dev. Never push directly.
dev         ← integration branch. Updated ONLY by PR from feature branches.
feat/*      ← feature work, branched FROM dev
fix/*       ← bug fixes, branched FROM dev
chore/*     ← maintenance, branched FROM dev

首要规则：始终先创建分支

编写任何代码之前——哪怕只是修复一行代码——都要从 dev 创建一个功能／修复／杂务分支。

不要：

• 在 dev 上开始编写代码，然后想着“之后再移到分支上”
• 将“快速修复”直接推送到 dev
• 认为小改动不需要创建分支

如果你当前在 dev 上，并且准备进行更改，请停下并运行：

git checkout -b feat/descriptive-name dev

一个功能对应一个分支

功能分支会一直保留到功能完成为止。所有相关工作都在该分支上进行：

• PR 审查反馈 → 在同一分支上修复并推送
• Copilot 评论 → 在同一分支上修复并推送
• 多轮迭代 → 使用同一分支

不要为审查尚未合并的 PR 时发现的问题新建 fix/ 分支。PR 合并前，请始终留在功能分支上。

只有在开始真正全新且无关的工作时，才需要创建新分支。

流程

1. git checkout -b feat/thing dev — 在进行任何代码更改之前创建分支
2. 在功能分支上提交更改
3. 推送功能分支，并创建目标为 dev 的 PR（绝不要指向 main）
4. 在同一分支上处理审查反馈，然后再次推送
5. 审批通过后，将 PR 合并到 dev
6. dev 稳定后，创建从 dev 到 main 的 PR

推送规则

操作	允许？
推送到功能分支	✅ 始终允许
推送到 dev	❌ 仅当用户明确说“push to dev”时允许
推送到 main	❌ 绝不允许。只有通过合并 PR 才会更新 main。

如果用户在你位于 dev 时说“提交这个”或“我们来提交”，不要推送。请询问：“要为此创建一个功能分支吗？”

PR 目标分支

源分支	PR 目标分支
feat/*、fix/*、chore/*	dev
dev	main

如果你正准备从功能分支创建目标为 main 的 PR，请停下——目标分支必须是 dev。

Devcontainer — SSH 和 AWS

SSH 密钥会直接从 ~/.ssh/contexts/personal/ 挂载到 /home/vscode/.ssh。这里不会转发 Agent——SSH_AUTH_SOCK 无关紧要。git push 能正常工作是因为密钥文件位于挂载目录中，而不是因为转发了套接字。

首次推送前请验证：

ssh -T [email protected]    # must say "Hi loxosceles!"
aws sts get-caller-identity    # must return account info

如果 SSH 失败：检查主机上的 ~/.ssh/contexts/personal/id_ed25519 是否存在，以及 known_hosts 中是否有 github.com 条目。如果 AWS 失败：检查 ~/.aws/contexts/<name>/credentials 中是否有有效的 [default] 配置。挂载的上下文配置位于 .devcontainer/docker-compose.yml。

---

应避免的常见错误

1. 未创建分支就开始工作 — 编写代码前始终检查 git branch --show-current。如果显示 dev，请先创建分支。
2. 将“小修复”推送到 dev — 没有小到可以跳过分支和 PR 流程的修复。否则之后处理 cherry-pick 会很麻烦。
3. 从功能分支创建目标为 main 的 PR — 功能分支的目标始终是 dev。
4. 用户说“我们来做 X”后忘记创建分支 — 任何新任务的第一步都是 git checkout -b。
5. 为审查修复创建新分支 — 留在当前功能分支上。一个功能对应一个分支，直到合并为止。