From ccf09a2e179bbbbaa1c47aba4f06b7473e104d75 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Mon, 29 Jun 2026 09:21:37 +0200 Subject: [PATCH 1/3] docs: remove learnings section from create-pr skill Drop the optional Learnings section and the PR learnings scanner reference. The self-learning loop it fed was never used. Co-Authored-By: Claude Opus 4.8 (1M context) --- .agents/skills/create-pr/SKILL.md | 20 -------------------- 1 file changed, 20 deletions(-) diff --git a/.agents/skills/create-pr/SKILL.md b/.agents/skills/create-pr/SKILL.md index dda1abfe8a96..f77afc70ab33 100644 --- a/.agents/skills/create-pr/SKILL.md +++ b/.agents/skills/create-pr/SKILL.md @@ -74,26 +74,6 @@ 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: - -```markdown -## Learnings - -- -``` - -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: From 09d6cfcf9f1924ccef913083d615c490432d9b43 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Mon, 29 Jun 2026 09:26:15 +0200 Subject: [PATCH 2/3] docs: add Netlify preview guidance to create-pr skill Document the optional @netlify entry-path stanza for focused PRs and how to add deploy-preview deep links derived from the PR number. Co-Authored-By: Claude Opus 4.8 (1M context) --- .agents/skills/create-pr/SKILL.md | 39 +++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/.agents/skills/create-pr/SKILL.md b/.agents/skills/create-pr/SKILL.md index f77afc70ab33..f226df95d5bc 100644 --- a/.agents/skills/create-pr/SKILL.md +++ b/.agents/skills/create-pr/SKILL.md @@ -74,6 +74,45 @@ 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---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 --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: From 0843b4b62ba5084b40dfc60e7f375d39f515244d Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Mon, 29 Jun 2026 09:29:18 +0200 Subject: [PATCH 3/3] docs: tighten branch and remote handling in create-pr skill - Guard against running on the default branch (main/master) - Use git status --porcelain to catch staged/unstaged changes, not just unstaged ones - Handle the case where origin is upstream docker/docs by pushing to a separate fork remote, and derive FORK_OWNER from that remote - Note the docs:/scope title prefix convention Co-Authored-By: Claude Opus 4.8 (1M context) --- .agents/skills/create-pr/SKILL.md | 36 +++++++++++++++++++++++++------ 1 file changed, 29 insertions(+), 7 deletions(-) diff --git a/.agents/skills/create-pr/SKILL.md b/.agents/skills/create-pr/SKILL.md index f226df95d5bc..2bec1eb3d360 100644 --- a/.agents/skills/create-pr/SKILL.md +++ b/.agents/skills/create-pr/SKILL.md @@ -12,23 +12,41 @@ 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 diff --quiet # confirm no unstaged changes +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 -Confirm origin points to your fork, not upstream: +Identify the remote that points at your fork. Inspect the remotes: ```bash -git remote get-url origin +git remote -v ``` -Then push: +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 -git push -u origin +FORK_REMOTE=origin # or the name of your fork remote if origin is upstream +git push -u "$FORK_REMOTE" ``` ## 3. Create the PR @@ -46,10 +64,10 @@ 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: +Derive the fork owner dynamically from the same fork remote you pushed to: ```bash -FORK_OWNER=$(git remote get-url origin | sed -E 's|.*[:/]([^/]+)/[^/]+(\.git)?$|\1|') +FORK_OWNER=$(git remote get-url "$FORK_REMOTE" | sed -E 's|.*[:/]([^/]+)/[^/]+(\.git)?$|\1|') ``` ```bash @@ -68,6 +86,10 @@ 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.