pr-descriptions

更新 PR 描述

概述

在某些 GitHub 实例或配置中，gh pr edit --body 可能会静默失败：命令已接受，但更改并未保存。当标准 CLI 工具无法按预期工作时，GitHub REST API 可作为可靠的备用方案。

适用场景

• gh pr edit --body 接受命令，但更改未保存（静默失败）
• 需要以编程方式更新包含多行内容的 PR 描述
• 使用复杂的 PR 模板，但编辑内容未能反映出来
• 继续操作前需要确保更改已保存

不适用的情况：

• gh pr edit --body-file 已成功更新 PR
• 只需更新标题或简单字段

核心模式

当 gh pr edit 未能保存更改时：

# Step 1: Get current PR details to verify number
gh pr view --json number -q '.number'

# Step 2: Try standard approach first
gh pr edit <PR_NUMBER> --body "$(cat <<'EOF'
[new body content]
EOF
)"

# Step 3: If no error but changes don't persist, use API directly
gh api repos/OWNER/REPO/pulls/<PR_NUMBER> -X PATCH -f body="$(cat <<'EOF'
[new body content]
EOF
)"

核心模式要素

使用 <<'EOF' heredoc（而不是 <<"EOF"）

单引号可防止 shell 展开：

# ✅ Correct - preserves backticks, $variables, special chars
gh api repos/owner/repo/pulls/123 -X PATCH -f body="$(cat <<'EOF'
Contains `backticks` and $special chars
EOF
)"

# ❌ Wrong - shell expands variables before API call
gh api repos/owner/repo/pulls/123 -X PATCH -f body="$(cat <<"EOF"
Contains `backticks` and $special (expands!)
EOF
)"

获取未知的 PR 编号

# From current branch (if tracking remote PR)
gh pr view --json number -q '.number'

验证 API 调用是否成功

检查返回的 JSON 是否包含你的正文：

gh api repos/owner/repo/pulls/123 -X PATCH -f body="new content" | grep -q "new content" && echo "Success"

实现

简单更新

PR_NUMBER=$(gh pr view --json number -q '.number')

gh api repos/Reckon-Limited/reckon-frontend/pulls/$PR_NUMBER -X PATCH -f body="$(cat <<'EOF'
# Summary

This PR implements feature X.

## Features
- Feature A
- Feature B

# Testing

EOF
)"

更新并验证

PR_NUMBER=$(gh pr view --json number -q '.number')
NEW_BODY="# Summary

This PR implements employee list actions."

gh api repos/Reckon-Limited/reckon-frontend/pulls/$PR_NUMBER -X PATCH -f body="$NEW_BODY"

# Verify by checking the returned body matches
gh pr view $PR_NUMBER --json body -q '.body' | head -1

常见错误

错误 1：heredoc 使用了错误的引号

# ❌ Wrong - variables expand, breaks formatting
gh api repos/owner/repo/pulls/123 -X PATCH -f body="$(cat <<"EOF"
Variables like $VAR and $(commands) will expand
EOF
)"

# ✅ Correct
gh api repos/owner/repo/pulls/123 -X PATCH -f body="$(cat <<'EOF'
Variables like $VAR and $(commands) stay literal
EOF
)"

错误 2：未检查返回值就认定操作成功

# ❌ Command returns 200 but changes don't persist
gh pr edit 123 --body "new content"  # exits 0, no error

# ✅ Use API and check response
gh api repos/owner/repo/pulls/123 -X PATCH -f body="new content" | grep -q "new content"

错误 3：忘记先尝试 --body-file

# ✅ Best practice order:
# 1. Try gh pr edit --body-file (file-based, more reliable than inline)
# 2. If that fails, use gh api (always works)
gh pr edit 123 --body-file my_body.md  # Try this first

错误 4：使用特殊字符时，正文字符串构建错误

# ❌ Wrong - newlines lost, special chars cause issues
BODY="# Summary\nNew content"
gh api repos/owner/repo/pulls/123 -X PATCH -f body="$BODY"

# ✅ Correct - use heredoc to preserve formatting
gh api repos/owner/repo/pulls/123 -X PATCH -f body="$(cat <<'EOF'
# Summary

New content
EOF
)"

故障排除

如果 API 调用返回 422 Unprocessable Entity：

• 检查 PR 编号是否正确：gh pr view --json number
• 检查仓库路径（OWNER/REPO）：gh api repos/Reckon-Limited/reckon-frontend --json nameWithOwner
• 验证身份验证状态：gh auth status

如果正文已更新，但包含转义后的换行符或格式问题：

• 使用带单引号的 heredoc：<<'EOF'，而不是 <<"EOF"
• 复杂内容不要使用内联字符串，改用 heredoc

如果命令成功，但 gh pr view 显示旧正文：

• 等待片刻（GitHub API 的最终一致性）
• 清除本地缓存：gh pr view --refresh
• 通过 GitHub 网页界面验证（浏览器可能会缓存）

实际影响

当 gh pr edit 静默失败时，使用 API 备用方案可确保自动化脚本可靠地更新 PR 描述，减少后续手动处理工作，并确保提供给审阅者的 PR 文档准确无误。