pull-request

name

pull-request

description

Open a GitHub pull request for the Sensei LMS Certificates plugin the way this repo requires. Use this whenever the user wants to create, open, draft, or "put up" a PR, or says things like "open a PR", "create a pull request", "make a PR for this branch", or "PR this". It fills the repo's PULL_REQUEST_TEMPLATE.md from the actual diff against trunk, commits the changelog entry (or applies the No Changelog label), assigns the required milestone, and stops for approval before pushing. Prefer this skill over a bare `gh pr create` so the PR carries its changelog entry and milestone, and so the body matches the template reviewers expect.

Open a Sensei LMS Certificates Pull Request

Fill the repo's PR template from the diff, do the required chores in the steps below, and stop for approval before gh pr create — which pushes the branch.

Who this is for

This skill assumes write access to woocommerce/sensei-certificates — it assigns the milestone (needs triage/write permission). One step doesn't apply to fork / external contributors:

• Milestone: external contributors can't assign one — leave it; a maintainer sets the milestone on their side.

Everything else (template body, changelog entry, testing instructions, stop-before-push) applies to everyone.

Base branch

The base is always trunk. Compare against it, not main.

Steps

1. Preconditions

• Confirm the current branch is not trunk. If it is, stop — nothing to PR.
• Confirm gh is authenticated: gh auth status. If not, ask the user to run ! gh auth login themselves.

2. Understand the change from the diff

Describe what the diff does, not how you got there — commit-by-commit narration is noise to a reviewer.

git merge-base trunk HEAD          # fork point
git log --oneline trunk..HEAD      # commits on this branch
git diff --stat trunk...HEAD       # files touched
git diff trunk...HEAD              # the actual change — read this

Read the diff. From it, decide the title — one line, imperative, concise, no conventional-commit prefix (no feat: / fix:). Example: Add course link to quiz page breadcrumb.

3. Fill the repo's PR template

Do not invent your own headings. Read the template and fill it in:

cat .github/PULL_REQUEST_TEMPLATE.md

Fill each section from the diff. Guidance per section:

• Resolves # — fill it in as Resolves #<n> if the user gave an issue number, or one appears in the branch name or the commit messages. If there's no issue, remove this line entirely — a bare Resolves # is noise. Never guess a number.
• ## Proposed Changes — the reviewer-facing summary. Lead with the problem or need and the user impact (new capability, bug fixed, performance, accessibility, behavior change or trade-off), then the approach at a high level. Don't re-list the modified files or narrate implementation mechanics — the diff already shows that; prose that just restates it wastes the reviewer's time. If the change is user-visible, a reader should understand what changes for them without opening the diff.
• ## Screenshots — keep this section only when the change is visual. Judge that from the diff: it touches front-end/editor surfaces — assets/ (JS/CSS/SCSS), block markup, render.php, front-end templates, or editor components. If it's not visual (pure PHP logic, REST, data, tooling, tests), remove this whole section. When you keep it, leave the template's empty Before/After table for the user to fill (for net-new UI with no "before" state, replace it with a note to paste a single screenshot or short video). You cannot capture the images yourself, so at the approval gate (step 5) remind the user to attach them.
• ## Testing Instructions — a checkbox list (- [ ] step) of manual steps a human follows to verify the change (click paths, expected on-screen results, edge cases), so the reviewer can tick each as they test. Never list running automated suites as a step — there are none; the reviewer verifies behavior by hand. If the change has no manual surface (e.g. test-only or pure internal refactor), say so briefly instead of padding with "run the tests".
• ## New/Updated Hooks — fill only if the diff adds or changes an action or filter; describe each and its args, and plan to add the Hooks label. If the diff touches no hooks, remove this whole section (heading, comment, and placeholder) from the body rather than leaving an empty *.
• ## Deprecated Code — fill only if the diff deprecates something; name the replacement and plan to add the Deprecation label. If nothing is deprecated, remove this whole section from the body.

4. Changelog — a committed entry, not the PR body

This repo uses Jetpack changelogger; entries live as files under changelog/ and are rolled into changelog.txt on release. CI lints PHP but does not generate the changelog, so the entry is a file you commit to the branch (or the PR carries the No Changelog label).

First check whether the branch already has an entry — a dev may have run npm run changelog during development and committed it:

git diff --name-only --diff-filter=A trunk...HEAD -- changelog/

If that lists a file, the entry already exists — note it in the summary you show the user.

• User-facing change (no committed entry yet): tell the user to run npm run changelog and commit the new changelog/ file with the PR — it's interactive, so don't run it for them. Write the Message as the user-facing outcome (one sentence — the effect, not the implementation). When the significance is ambiguous (e.g. a fix/ branch that repairs behavior but also adds a small element), lean toward Patch / Fixed — match how the work is framed rather than over-classifying it as a feature.
• Internal-only change (refactor, test-only, tooling — no user-facing effect): plan to apply the No Changelog label to the PR. Say this in the summary you show the user.

5. Stop and confirm — this is the push gate

Show the user the proposed title and the filled template body (call out the changelog choice and any labels: Hooks / Deprecation / No Changelog). If you kept a Screenshots section, remind the user to attach before/after images — you can't capture them, and the placeholder ships empty otherwise. Then wait for explicit approval. Do not run gh pr create until they say go — it pushes the branch and opens the PR, which is outward-facing and hard to walk back.

6. Create the PR

After approval:

gh pr create --base trunk --title "<title>" --body "<filled template body>"

gh pushes the current branch as part of this. Capture the PR number it prints. Apply any labels you flagged (e.g. No Changelog, Hooks, Deprecation), and assign the PR to its author (@me is the authenticated user opening it):

gh pr edit <PR_NUMBER> --add-label "No Changelog"
gh pr edit <PR_NUMBER> --add-assignee "@me"

7. Assign the milestone (required)

Find the next shipping milestone (lowest-versioned open one) and assign it. Use sort -V (version sort) — a plain string sort mis-orders 2.5.5 vs 2.10.0:

next=$(gh api 'repos/woocommerce/sensei-certificates/milestones?state=open' --jq '.[].title' | sort -V | head -1)
gh pr edit <PR_NUMBER> --milestone "$next"

8. Wrap up

Give the user the PR URL.