create-pr

name	create-pr
description	Push the current branch and create a pull request against docker/docs. Use after changes are committed and reviewed. "create a PR", "submit the fix", "open a pull request for this".

Create PR

Push the branch and create a properly structured pull request.

1. Verify the branch

git log --oneline main..HEAD   # confirm commits exist
git diff --quiet               # confirm no unstaged changes

2. Push the branch

Confirm origin points to your fork, not upstream:

git remote get-url origin

Then push:

git push -u origin <branch-name>

3. Create the PR

Before creating a PR for an issue, check whether that issue already has an open linked PR:

gh api repos/docker/docs/issues/<issue-number>/timeline --paginate \
  --jq '.[] | select((.event=="cross-referenced" or .event=="connected" or .event=="referenced") and .source.issue.pull_request and .source.issue.state=="open") | {url: .source.issue.html_url, title: .source.issue.title}'

If this returns an open PR that addresses the same issue, stop. Don't open a duplicate PR; report the existing PR instead. Only proceed if there is no open linked PR, or if the existing PR clearly does not address the issue and you explain why in the new PR body.

Derive the fork owner dynamically:

FORK_OWNER=$(git remote get-url origin | sed -E 's|.*[:/]([^/]+)/[^/]+(\.git)?$|\1|')

gh pr create --repo docker/docs \
  --head "${FORK_OWNER}:<branch-name>" \
  --title "<concise summary under 70 chars>" \
  --body "$(cat <<'EOF'
## Summary

<1-2 sentences: what was wrong and what was changed>

Closes #NNNN

Generated by <active coding agent name>
EOF
)"

Keep the body short. Reviewers need to know what changed and why — nothing else. Do not add a "Test plan" section — documentation PRs don't need one.

Use an accurate disclosure footer that names the active coding agent, for example Generated by Codex or Generated by Claude Code.

Optional: Learnings section

If while working on this PR you discovered something non-obvious about the repo — a convention not documented in AGENTS.md, a gotcha that tripped you up, a pattern that should be codified — add a Learnings section to the PR body:

## Learnings

- <what you learned and why it matters>

Add this section between the Summary and the Closes line. Only include learnings that would help future contributors avoid the same issue. Do not include things already documented in AGENTS.md or STYLE.md.

The weekly PR learnings scanner reads these sections to surface recurring patterns for the team to codify.

4. Apply labels and request review

Use the Issues API for labels — gh pr edit --add-label silently fails:

gh api repos/docker/docs/issues/<pr-number>/labels \
  --method POST \
  --field 'labels[]=status/review'

Request review:

gh pr edit <pr-number> --repo docker/docs --add-reviewer docker/docs-team

Verify the reviewer was assigned:

gh pr view <pr-number> --repo docker/docs --json reviewRequests \
  --jq '.reviewRequests[].slug'

If the team doesn't appear, use the API directly:

gh api repos/docker/docs/pulls/<pr-number>/requested_reviewers \
  --method POST --field 'team_reviewers[]=docs-team'

5. Report

Print the PR URL and current CI state:

gh pr view <pr-number> --repo docker/docs --json url,state
gh pr checks <pr-number> --repo docker/docs --json name,state

Notes

• Always use Closes #NNNN (not "Fixes") for GitHub auto-close linkage
• One issue, one branch, one PR — never combine