writing-github-pr-descriptions（writing GitHub PR descriptions 前端）

Updating PR Descriptions

Overview

gh pr edit --body can fail silently on some GitHub instances or configurations, accepting the command but not persisting changes. The GitHub REST API provides a reliable fallback when standard CLI tools don't work as expected.

When to Use

• gh pr edit --body accepts command but changes don't persist (silent failure)
• Need to programmatically update PR description with multiline content
• Working with complex PR templates where edits aren't reflected
• Need guaranteed persistence before moving forward

Not needed when:

• gh pr edit --body-file successfully updates your PR
• You only need to update title or simple fields

Core Pattern

When gh pr edit doesn't persist:

# 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
)"

Key Pattern Elements

Use heredoc with <<'EOF' (not <<"EOF")

The single quotes prevent shell expansion:

# ✅ 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
)"

Get PR number if unknown

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

Verify API call succeeded

Check the returned JSON contains your body:

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

Implementation

Simple Update

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
<!-- Testing notes -->
EOF
)"

Update with Verification

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

Common Mistakes

Mistake 1: Using wrong quoting for 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
)"

Mistake 2: Not checking return value before assuming success

# ❌ 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"

Mistake 3: Forgetting --body-file as intermediate step

# ✅ 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

Mistake 4: Building body string incorrectly with special chars

# ❌ 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
)"

Troubleshooting

If API call returns 422 Unprocessable Entity:

• Check PR number is correct: gh pr view --json number
• Check repository path (OWNER/REPO): gh api repos/Reckon-Limited/reckon-frontend --json nameWithOwner
• Verify authentication: gh auth status

If body updates but contains escaped newlines or formatting issues:

• Use heredoc with single quotes: <<'EOF' not <<"EOF"
• Avoid inline strings for complex content - use heredoc

If command succeeds but gh pr view shows old body:

• Wait a moment (GitHub API eventual consistency)
• Clear any local cache: gh pr view --refresh
• Verify via GitHub web UI (browser may cache)

Real-World Impact

Using the API fallback when gh pr edit silently fails ensures PR descriptions are reliably updated in automation scripts, reducing manual follow-up work and ensuring accurate PR documentation for reviewers.