---
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

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

```bash
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:

```markdown
@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:

```bash
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:

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

Request review:

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

Verify the reviewer was assigned:

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

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

```bash
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:

```bash
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