|
| 1 | +--- |
| 2 | +name: pr-mr |
| 3 | +description: Creates and updates pull requests and merge requests for cloudflare-docs changes. Covers title conventions, branch naming, request body structure, and documentation checklist templates. Load when asked to open, create, submit, update, or edit a PR or MR, or write a PR or MR title or description. |
| 4 | +--- |
| 5 | + |
| 6 | +Use this skill to prepare, create, and update pull requests and merge requests. |
| 7 | + |
| 8 | +## Repository operations |
| 9 | + |
| 10 | +Identify the hosting provider and target repository from the current repository's remotes and configuration. Do not assume a provider or hardcode a remote URL. |
| 11 | + |
| 12 | +Use the available integration or authenticated CLI for that provider to read, create, and update requests. If the syntax is uncertain, check the tool's help before running a command that changes remote state. |
| 13 | + |
| 14 | +When the provider tool supports reading a body from a file, write the complete Markdown body to a temporary file and use the file-input option instead of passing the body inline through the shell. This preserves backticks, newlines, and other Markdown formatting. Remove the temporary file afterward. |
| 15 | + |
| 16 | +If no provider integration or authenticated CLI is available, stop and explain the blocker instead of claiming that the request was created or updated. |
| 17 | + |
| 18 | +## Editing an existing request |
| 19 | + |
| 20 | +When asked to update or edit an existing request description (or title), follow these rules strictly. Do not create a new request. |
| 21 | + |
| 22 | +1. **Always read the current request title, description, and target branch first** before making any changes. |
| 23 | +2. **If the description is empty**, treat it as a new request body and follow Steps 1–3 in the "Creating a new request" section below. Apply the result to the existing request; do not create another request. |
| 24 | +3. **Follow the existing format** — if the author has structured their description in a particular way, preserve that structure. Do not reformat, reorder, or restructure sections they wrote. |
| 25 | +4. **Only change what was asked** — make the minimum edit necessary to fulfill the request. Do not "improve" unrelated phrasing, fix grammar elsewhere, rewrite the summary, or modify checklist items that were not part of the request. |
| 26 | +5. Apply the requested title or description changes using the provider tool selected under "Repository operations." |
| 27 | + |
| 28 | +## After pushing to a branch with an open request |
| 29 | + |
| 30 | +Whenever you push new commits to a branch that already has an open request, check whether its title and description still accurately describe what the branch now does. New commits often add scope the original description does not mention. |
| 31 | + |
| 32 | +1. Check whether the branch has an open request. |
| 33 | +2. Compare the title and body against the full branch diff (`git diff <base>...HEAD --stat`), using the request's target branch as `<base>`, not just the latest commit. |
| 34 | +3. If they are now inaccurate or incomplete, update them following the "Editing an existing request" rules above — preserve the author's structure and make the minimum edit needed to reflect the new changes. If they still describe the branch correctly, leave them unchanged. |
| 35 | + |
| 36 | +Do this proactively after a push; you do not need to be asked separately to keep the request in sync. |
| 37 | + |
| 38 | +## Creating a new request |
| 39 | + |
| 40 | +Follow Steps 1–4 below only when creating a new request. For an existing request with an empty description, follow Steps 1–3 and update that request as described above. |
| 41 | + |
| 42 | +## Step 1 — Gather context |
| 43 | + |
| 44 | +Determine the request's target branch first; this is `<base>`. For an existing request, use its current target branch. For a new request, use `production` unless the user asked for a different base. Then run `--stat` to understand the scope without blowing up context: |
| 45 | + |
| 46 | +```bash |
| 47 | +git log --oneline <base>..HEAD |
| 48 | +git diff <base>...HEAD --stat |
| 49 | +git status |
| 50 | +``` |
| 51 | + |
| 52 | +**If `git status` shows untracked or modified files**, stop and ask the user whether those files should be committed as part of this request before proceeding. Do not silently ignore them — they may be integral to the work being submitted. |
| 53 | + |
| 54 | +If the stat output shows more than ~20 files changed, do **not** run the full diff. Instead, read specific files that are unclear from the stat output. For smaller changesets (under ~20 files), the full diff is fine: |
| 55 | + |
| 56 | +```bash |
| 57 | +git diff <base>...HEAD |
| 58 | +``` |
| 59 | + |
| 60 | +## Step 2 — Write the request title |
| 61 | + |
| 62 | +### Branch: `production` |
| 63 | + |
| 64 | +This repo uses `production` as the default branch, not `main`. Contributors from other repos often expect `main` — this is intentional. |
| 65 | + |
| 66 | +Create feature branches off an up-to-date `production` commit unless the user asked for a different base. |
| 67 | + |
| 68 | +### Format |
| 69 | + |
| 70 | +For content changes, the dominant convention is product brackets: |
| 71 | + |
| 72 | +``` |
| 73 | +[Product] Short description |
| 74 | +``` |
| 75 | + |
| 76 | +For changes spanning multiple products: |
| 77 | + |
| 78 | +``` |
| 79 | +[Product1, Product2] Short description |
| 80 | +``` |
| 81 | + |
| 82 | +For non-content changes such as tooling, CI, configuration, components, worker code, or repository maintenance, use a conventional commit prefix: |
| 83 | + |
| 84 | +``` |
| 85 | +chore: Short description |
| 86 | +fix: Short description |
| 87 | +feat: Short description |
| 88 | +``` |
| 89 | + |
| 90 | +### Inferring the product bracket from file paths |
| 91 | + |
| 92 | +Do not ask the author what product bracket to use — infer it from the changed file paths. |
| 93 | + |
| 94 | +- `src/content/docs/{slug}/` and `src/content/partials/{slug}/` map directly to a product. Read the `title` field from `src/content/docs/{slug}/index.mdx` to get the display name, then strip any "Cloudflare " prefix to get the bracket (e.g. title "Cloudflare Workers" → `[Workers]`). |
| 95 | +- `src/content/changelog/{slug}/` maps the same way — use the product bracket, not `[Changelog]`. Use `[Changelog]` only when the request exclusively adds or updates changelog entries across multiple products. |
| 96 | +- If the change spans more than 3 products, use the 2–3 most prominent ones. |
| 97 | + |
| 98 | +### Rules |
| 99 | + |
| 100 | +- Use title case for product names inside brackets: `[Workers]`, `[AI Search]`, `[Zero Trust]` |
| 101 | +- Keep the description under ~60 characters |
| 102 | +- Use imperative mood: add, fix, update, remove, document, correct |
| 103 | +- Do not end with a period |
| 104 | +- Common abbreviations in brackets: `[DO]` for Durable Objects, `[KV]`, `[ZT]` for Zero Trust, `[R2]`, `[D1]` |
| 105 | + |
| 106 | +### Title examples |
| 107 | + |
| 108 | +``` |
| 109 | +[AI Search] Add hybrid search and boosting configuration docs |
| 110 | +[Hyperdrive, Workers VPC] Document TCP services, TLS cert verification |
| 111 | +[Browser Rendering] Add Wrangler CLI commands documentation |
| 112 | +[Billing] Restructure billing docs into intent-based sections |
| 113 | +[DMARC Management] ELI5 |
| 114 | +[Client-side security] ELI5 updates |
| 115 | +[DNS, Fundamentals] Onboarding review and add video |
| 116 | +[Style Guide] Adding products frontmatter to all visible examples |
| 117 | +[Workers] Document Durable Object Facets |
| 118 | +[Changelog] CDP + WebMCP changelog entries |
| 119 | +``` |
| 120 | + |
| 121 | +Use the `[Product]` bracket format as your default for content changes. Use conventional commit prefixes for non-content changes. |
| 122 | + |
| 123 | +## Step 3 — Write the request body |
| 124 | + |
| 125 | +Read the request template from the repository before writing the body. Use it as the exact base for the request body. Do not rely on any hardcoded version of the template — always read it fresh from disk in case it has changed. |
| 126 | + |
| 127 | +### How to fill out each section |
| 128 | + |
| 129 | +### Summary |
| 130 | + |
| 131 | +Write a short explanation covering: |
| 132 | + |
| 133 | +- What type of documentation is being changed (new page, update, fix, restructure, changelog entry) |
| 134 | +- Why the change is needed or what prompted it |
| 135 | +- Links to any relevant public context: issues, related PRs, or public docs pages. |
| 136 | + |
| 137 | +This is a public, open-source repository. Do not include private Cloudflare information, secrets, credentials, environment variable values, or URLs and titles of internal resources (tickets, wiki pages, internal docs) in request titles, descriptions, or comments. If there is any doubt about whether something is safe to publish, stop and ask the user. |
| 138 | + |
| 139 | +Keep it factual. Do not repeat what the checklist items say. For small, focused requests 1-2 sentences is enough. For larger requests touching many files or multiple areas, a longer description is appropriate — use tables, lists, or code blocks over paragraphs of prose where it makes the summary easier to scan. |
| 140 | + |
| 141 | +Good examples: |
| 142 | + |
| 143 | +Small, focused request: |
| 144 | + |
| 145 | +> Adds a caution note for the `active` attribute mapping behavior in SCIM provisioning. |
| 146 | +> |
| 147 | +> Fixes #1234 |
| 148 | +
|
| 149 | +Medium request: |
| 150 | + |
| 151 | +> Updates the Access policies index to reflect the new policy grouping UI. Fixes stale screenshots and outdated step ordering. |
| 152 | +
|
| 153 | +Larger request spanning multiple areas: |
| 154 | + |
| 155 | +> Restructures the billing docs into intent-based sections to make it easier for users to find pricing and usage information. |
| 156 | +> |
| 157 | +> | Before | After | |
| 158 | +> | ---------------------- | ------------------------------ | |
| 159 | +> | `billing/usage.mdx` | `billing/usage-and-limits.mdx` | |
| 160 | +> | `billing/limits.mdx` | _(merged into above)_ | |
| 161 | +> | `billing/overview.mdx` | `billing/index.mdx` | |
| 162 | +> |
| 163 | +> - Updated all internal links pointing to moved pages |
| 164 | +> - Added redirects for all renamed files |
| 165 | +
|
| 166 | +### Screenshots (optional) |
| 167 | + |
| 168 | +Skip this section entirely unless the request changes something visual — new pages, rearranged navigation, updated UI steps, or modified images. Do not leave the empty comment placeholder if screenshots are not needed. |
| 169 | + |
| 170 | +If the request does change something visual, include the section with a `<!-- TODO: add screenshots before requesting review -->` comment so the human knows to fill it in before the request is ready for review. |
| 171 | + |
| 172 | +### Documentation checklist |
| 173 | + |
| 174 | +Go through each item and decide whether it applies: |
| 175 | + |
| 176 | +1. **Changelog entry** — Required if the request documents a new feature, enhancement, or noteworthy change to a Cloudflare product. Remove this item if the request is a fix, typo correction, internal restructure, or style update. |
| 177 | + |
| 178 | +2. **Style guide adherence** — Check the diff for files under `src/content/` or authored component files (`.mdx`, `.astro`, `.css`). Keep this item **only** if at least one such file was added or modified. Remove this item if the request exclusively changes source code (`.ts`, `.tsx`, `.js`), tooling, CI, configuration files, agent skills, or any other non-content assets — even if those files live under `src/` or happen to be Markdown. |
| 179 | + |
| 180 | +3. **Issue opened for larger changes** — Keep this item if the request adds a new page, restructures a section, or addresses known inaccuracies. Remove it for small focused changes. |
| 181 | + |
| 182 | +4. **Redirects for renamed/moved files** — Keep this item if any `.mdx` files were renamed, moved, or deleted. Remove it if no files changed location. |
| 183 | + |
| 184 | +Remove individual checklist items that genuinely do not apply. Do not leave unchecked items that are irrelevant — they create noise for reviewers. Only remove the entire Documentation checklist section if **none** of the items apply (e.g. a pure CI or tooling change). If even one item applies, keep the section and remove only the irrelevant items. |
| 185 | + |
| 186 | +### What not to do |
| 187 | + |
| 188 | +- **Context-free rewrites** — If the request significantly changes or restructures content, the summary must explain what changed and why. A diff with no explanation forces reviewers to reverse-engineer intent. |
| 189 | +- **Diff narration** — Do not summarise the request by listing what changed line by line ("changed X to Y on line 42", "updated heading from A to B"). Explain why the change was made, not what it mechanically did. |
| 190 | +- **Cross-product changes without explanation** — If the request touches files across multiple product areas, explain the connection. Unrelated-looking changes with no stated reason are a red flag for reviewers. |
| 191 | +- **Pruning the checklist wrong** — Remove individual items that do not apply. Do not delete the entire checklist section unless none of the items are relevant. Reviewers use the remaining items to quickly verify coverage. |
| 192 | + |
| 193 | +## Step 4 — Create the request |
| 194 | + |
| 195 | +Build the request body by starting from the template read in Step 3 — replace the summary placeholder comment with the actual summary, remove checklist items that do not apply, and handle the screenshots section per the guidance above. |
| 196 | + |
| 197 | +Confirm that the branch and its commits are available to the hosting provider. If they must be pushed and the user has not authorized a push, ask for permission before pushing. |
| 198 | + |
| 199 | +Before creating a request, check for an existing open request with the same head branch and target `<base>`. If one exists, update or return that request instead of creating a duplicate. |
| 200 | + |
| 201 | +Create the pull request or merge request against the resolved `<base>` using the provider tool selected under "Repository operations." Create it as a draft when the hosting provider supports drafts. The author should review the deploy preview before marking a draft ready or requesting review for a request that cannot be drafted. |
| 202 | + |
| 203 | +## Output |
| 204 | + |
| 205 | +Share the pull request or merge request URL and its draft or review status. |
0 commit comments