commit-push-pr-workflow

提交、推送与 PR 工作流

适用于此仓库的约定：

• 不要直接提交到 main；请使用功能分支并创建 PR。
• PR/议题标题：使用英文。PR 正文/评论：默认使用简体中文（除非请求以 [EN] 开头）。
• 避免在 GitHub CLI 中使用带转义换行符的 --body；优先使用 --body-file 或标准输入，以免产生字面量 \\n。

本技能旨在适用于 Windows（PowerShell 5.1+）。Bash 示例为可选内容。

分支

• 进行更改前，从 main 创建功能分支：
  • git fetch origin --prune
  • git switch main
  • git pull --ff-only
  • git switch -c docs/example-change

提交

• 提交前，确认当前更改范围所需的检查已运行（记录确切命令）。
• 仅暂存计划提交的文件（优先使用 git add -p）。
• 使用文件编写提交消息（避免多个 -m 带来的格式问题）。
• 提交标题：采用 prefix: subject 或 prefix(scope): subject 格式，仅使用英文，最好不超过 50 个字符（硬性上限为 72 个字符），末尾不要加句点。
• 对于非简单更改，添加正文：标题后空一行，按每行 72 列换行，并注明风险和验证情况。

模板（PowerShell，UTF-8 无 BOM）

$msg = @'
fix(scope): concise subject

What changed, why, how (if relevant). Wrap at 72 columns.
Risks/side effects if any.
'@

$path = Join-Path $env:TEMP 'commit_msg.txt'
[System.IO.File]::WriteAllText($path, $msg, [System.Text.UTF8Encoding]::new($false))
git commit -F $path
Remove-Item -Force $path

模板（Bash，可选）

cat <<'EOF' > /tmp/commit_msg.txt
fix(scope): concise subject

What changed, why, how (if relevant). Wrap at 72 columns.
Risks/side effects if any.
EOF

git commit -F /tmp/commit_msg.txt
rm -f /tmp/commit_msg.txt

推送

• 检查通过后再推送。
• 对新分支，优先使用 git push -u origin <branch>。
• 避免强制推送。
  • 如果必须重写历史记录（例如，清除泄露的凭据），请明确确认，并注意分支规则（例如，默认分支上的非快进更新）可能会阻止强制推送，除非临时调整规则。
  • 如果使用了 git-filter-repo，它可能会自动移除 origin；推送前请重新添加。

推送前检查清单

• 已执行检查（已记录确切命令）。
• 提交标题/正文符合仓库规则。
• 用户已明确批准推送（尤其是使用 --force 时）。

PR

• 默认创建草稿 PR。

选项 A：GitHub CLI（gh）

gh --version
gh auth status

@'
Summary:
- ...

Verification:
- ...
'@ | gh pr create --draft --base main --title "docs: ..." --body-file -

选项 B：浏览器（无需额外工具）

• 推送分支，然后打开：
  • https://github.com/<owner>/<repo>/pull/new/<branch>

选项 C：GitHub API（PowerShell，编码安全）

• 优先使用环境变量令牌（不要在日志中回显令牌）：
  • $env:GITHUB_TOKEN = '...'

$headers = @{
  Authorization = "token $env:GITHUB_TOKEN"
  'User-Agent' = 'codex-cli'
  Accept = 'application/vnd.github+json'
}

$payload = @{
  title = 'docs: ...'
  head  = '<branch>'
  base  = 'main'
  body  = @"
Summary:
- ...

Verification:
- ...
"@
  draft = $true
} | ConvertTo-Json

$bytes = [System.Text.Encoding]::UTF8.GetBytes($payload)
Invoke-RestMethod -Method Post `
  -Uri 'https://api.github.com/repos/<owner>/<repo>/pulls' `
  -Headers $headers `
  -ContentType 'application/json; charset=utf-8' `
  -Body $bytes

选项 D：通过 git 凭据使用 GitHub API（PowerShell，无需环境变量令牌）

• 如果未安装 gh，且未设置 GITHUB_TOKEN，可以复用 git 已有的 GitHub 凭据：

$cred = "protocol=https`nhost=github.com`n`n" | git credential fill
$token = (($cred | Select-String -Pattern '^password=').Line).Substring(9)

$headers = @{
  Authorization = "token $token"
  'User-Agent'  = 'codex-cli'
  Accept        = 'application/vnd.github+json'
}

$payloadObj = @{
  title = 'docs: ...'
  head  = '<branch>'
  base  = 'main'
  body  = "Summary:`n- ...`n"
  draft = $true
}

$json  = $payloadObj | ConvertTo-Json -Depth 5
$bytes = [System.Text.Encoding]::UTF8.GetBytes($json)

Invoke-RestMethod -Method Post `
  -Uri 'https://api.github.com/repos/<owner>/<repo>/pulls' `
  -Headers $headers `
  -ContentType 'application/json; charset=utf-8' `
  -Body $bytes

如果通过 PowerShell 使用 GitHub API 编辑 PR 正文：

• 将 JSON 序列化为 UTF-8 字节（无 BOM），以可靠保留中文文本。
• 避免输出令牌或 Authorization 标头。