checkout-commit-push-pr

完整 Git 工作流

不要问我该怎么做。只需遵循以下工作流。唯一的例外：有可疑的未跟踪文件（见步骤 2）或本地默认分支已分叉（见步骤 1）时，请停止并指出问题，不要自行猜测。

1. 检查当前分支和更改

   通过以下命令执行

   git status
   

   检查所有待处理的更改，以便撰写 Git 提交/PR 消息——普通的 git diff 只会显示已跟踪文件中尚未暂存的编辑，因此也要检查已经暂存的内容：

   git diff
   git diff --staged
   

   对于打算提交的未跟踪文件，请读取其内容——新文件本身就是 更改，而任何 diff 命令都不会显示它。

   确定仓库的默认分支——不要假定它是 main：

   # Fast and local (may error if origin/HEAD is unset on older clones)
   git symbolic-ref --short refs/remotes/origin/HEAD | sed 's|^origin/||'
   
   # Fallback if the above errors
   gh repo view --json defaultBranchRef -q .defaultBranchRef.name
   

   如果当前已在非默认分支上，就留在该分支。 只有当前位于默认分支时才创建新分支——无论默认分支叫什么（main、master、develop 等），都绝不要直接向默认分支提交或推送。

   如果当前位于默认分支，请按以下命名约定创建并切换到新分支：

   [optional LINEAR-IDENTIFIER-][2-4 descriptive words]-[MMDD]
   

   • LINEAR-IDENTIFIER （可选）：如果这项工作对应已知的 Linear 问题，请在分支名前加上其标识符（例如 DATA-24-）。这样后续工具就能从分支名中找到该问题，并将 PR 与其关联。
   • 2-4 个词：使用小写字母，以连字符分隔，描述要修复的问题
   • 日期：今天的日期，格式为 MMDD（例如，7 月 12 日 → 0712）

   示例：

   • fix-sqlfluff-errors-1214（12 月 14 日）
   • update-dbt-models-0103（1 月 3 日）
   • DATA-24-improve-dagster-debug-skill-0527（带问题标识符前缀）

   创建分支前，确保本地默认分支已更新，以免新分支基于过时代码（过时的基底会导致 PR 出现无关差异和本可避免的冲突）。未提交的本地更改可以保留——git pull --ff-only 不会动它们；如果因本地分支已分叉而失败，请停止并指出问题，不要自行变基或合并。

   git pull --ff-only
   git checkout -b <new-branch-name-MMDD>
   

2. 有选择地暂存文件，并使用描述性消息提交：

   暂存任何内容前，先检查步骤 1 中 git status 报告的内容：

   • 已修改/已删除的已跟踪文件：全部暂存——这些就是要交付的工作。
   • 未跟踪文件：只暂存属于此次更改的文件。不要暂存看起来像机密、本地配置或临时输出的文件（例如 .env*、credentials*、*.key、.DS_Store、编辑器交换文件、大型数据转储、一次性调试脚本）。如果某个未跟踪文件含义不明确，请先读取。
   • 如果要提交的内容中有可疑文件，请停止并告知我，不要自行猜测。

   # Stage all tracked changes
   git add -u
   
   # Stage intended untracked files explicitly, by name
   git add <new-file-1> <new-file-2>
   
   # Confirm exactly what will be committed
   git status
   git diff --staged --stat
   
   # Commit with descriptive message, informed by the diff from step 1
   git commit -m "<Overview of the change>
   
   - <item 1 in the more specific bulleted list of changes>
   - ...
   "
   

3. 检查 PR 模板：

   创建 PR 前，检查仓库是否有 PR 模板：

   # Check common PR template locations
   ls .github/pull_request_template.md .github/PULL_REQUEST_TEMPLATE.md PULL_REQUEST_TEMPLATE.md 2>/dev/null
   

   • 如果存在模板，请阅读并按其结构撰写 PR 正文
   • 填写模板中的所有必填部分
   • 如果没有模板，请使用下方的默认格式

   如果此时已知 Linear 问题——无论是由编排器传入（例如 wrap-up-session），还是从 LINEAR-IDENTIFIER-… 分支名前缀自动检测到——都要在 PR 正文靠上位置加入问题关闭引用和 **Ticket:** 行，以便 PR 创建时就与该问题关联：

   Fixes DATA-24
   **Ticket:** [DATA-24](https://linear.app/citizen/issue/DATA-24)
   

   使用问题的实际 URL。只有当 PR 完成该问题时才使用 Fixes；否则使用 Refs。将这两行直接插在第一个标题下方（例如，使用模板时直接放在 ## Description & motivation 下方）。如果不知道问题标识符，则省略这两行。由 wrap-up-session 调用时，后续的 linear-ticket-management 步骤会创建或更新问题，并将其与 PR 交叉关联。单独调用时不会创建问题。

4. 推送分支并创建 PR：

   # Push to remote
   git push -u origin <new-branch-name-MMDD>
   
   # Create pull request (use template structure if found, otherwise use default)
   gh pr create --title "<Descriptive PR Title>" --body "$(cat <<'EOF'
   

Summary

• <what changed and why, in a few bullets>

Changes

• <specific change 1>
• ... EOF )"

  
  注意，heredoc 正文和结束标记 `EOF` 都从第 0 列开始——如果它们有缩进，
  `EOF` 就不会终止 heredoc。
  
  **确保输出 PR 链接**（`gh pr create` 会打印该链接）。
  

5. 监控 CI/CD 检查： 创建 PR 后，监控 CI/CD 流水线，确保所有检查均通过：

   # Block until all checks complete — no manual polling needed
   # (add --fail-fast to return as soon as any check fails)
   gh pr checks <PR-NUMBER> --watch
   
   # View detailed information about a specific workflow run
   gh run view <RUN-ID>
   
   # View logs for a failed job
   gh run view --log-failed --job=<JOB-ID>
   

   重要： 在两种不同情况下，gh pr checks 会返回“no checks reported”并以退出码 1 结束：(a) 仓库没有工作流；或 (b) 仓库有工作流，但尚未注册（推送后通常需要 10-30 秒）。不要仅凭此输出就断定“未配置 CI”。

   • 首先检查 ls .github/workflows/ ——如果其中有任何文件，就说明已配置 CI，你必须等待。
   • 优先使用 gh pr view <PR-NUMBER> --json statusCheckRollup，它可以区分“没有工作流”和“待处理”。
   • 如果仓库有工作流，但检查尚未出现，等待约 30 秒后重新检查。

   目标：所有必需检查均通过。 无论仓库运行哪些检查——代码检查、构建、测试、文档验证——都要处理每项失败的必需检查。

   处理检查失败：

   • 查看失败作业的日志（gh run view --log-failed），找出实际错误——不要根据检查名称猜测。
   • 在本地修复问题，提交并推送到同一分支；检查会自动重新运行。重复此过程，直至全部通过。
   • 对于机械性修复，优先使用仓库自身的工具（例如运行检查所用的格式化工具或代码检查工具；如果提供自动修复功能，则使用该功能）。
   • 如果失败并非由你的差异导致（例如不稳定的测试、基础设施错误、缺少必须先创建的前置状态），请停止并标记问题，而不是反复提交。

   可接受的跳过检查：

   • 非生产分支上的仅限生产环境检查
   • 不适用于你所做更改的条件检查

   所有检查通过后：

   • PR 已准备好进行审查和合并
   • 所有验证均已成功，代码质量得到保障

提交消息格式

• 第一行：简要概述更改
• 正文：以项目符号列出具体更改
• 不要附加 Co-Authored-By: Claude 标记（或任何其他自动生成的署名）