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

Confirm you're on a dedicated branch, not the default branch:

git branch --show-current   # must not be main or master

If this returns main or master, stop. Create a branch and move your commits onto it before continuing.

Confirm commits exist and the working tree is clean:

git log --oneline main..HEAD   # confirm commits exist
git status --porcelain         # must print nothing

If git status --porcelain prints anything, there are uncommitted or unstaged changes. Stop and commit them — or unstage stray files like package-lock.json — before opening a PR. Don't open a PR mid-edit.

2. Push the branch

Identify the remote that points at your fork. Inspect the remotes:

git remote -v

If origin is your fork, use it. If origin points at canonical docker/docs (the upstream), push to your separate fork remote instead — never push the branch to docker/docs directly:

FORK_REMOTE=origin   # or the name of your fork remote if origin is upstream
git push -u "$FORK_REMOTE" <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 from the same fork remote you pushed to:

FORK_OWNER=$(git remote get-url "$FORK_REMOTE" | 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
)"

Prefix the title with the change type to match repo convention — docs: for documentation changes (or another scope like hub: when appropriate), for example docs: fix broken link on install page.

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: Netlify preview entry path

If the PR primarily edits a single page or a focused section of pages, add a @netlify stanza to the PR body (for example, just below the Summary). This sets the entry path for the Netlify deploy preview so reviewers land on the edited page instead of the site root:

@netlify /desktop/setup/install/

The stanza takes a single published URL path. Derive it from the source file path: drop the content/ prefix and .md suffix, strip the /manuals segment, and add a trailing slash. For example, content/manuals/desktop/setup/install/mac-install.md becomes /desktop/setup/install/mac-install/.

Only add this when the change is focused on one page or section. Skip it for PRs that touch many unrelated pages — there is no useful single entry path.

Optional: Preview links

When the change is focused, also add direct links to the deploy preview in the PR body so reviewers can jump straight to the affected pages. The preview URL embeds the PR number:

https://deploy-preview-<pr-number>--docsdocker.netlify.app/path/to/page/

The PR number isn't known until gh pr create returns, so add these links after creating the PR by updating the body:

gh pr edit <pr-number> --repo docker/docs --body "..."

Use the same source-path-to-URL mapping as the @netlify stanza above.

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