create-pr

# 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