github-pr-conventions

Files (1)

• SKILL.md

SKILL.md (first lines)

# GitHub pull request conventions (`gh` CLI)

## Rebase onto its base before opening it

**A PR is opened from a branch that has just been rebased onto its up-to-date
base branch** — `main`, or the parent's branch for a stacked PR (see below) —
always, even when the branch is an hour old and the diff looks unrelated to
everything that landed since:

```bash
git fetch origin
git rebase origin/main
```

Before `gh pr create`, not after a reviewer trips over a conflict marker. What
it buys, and why "it'll merge fine anyway" is not a reason to skip it:

- **The PR's diff is the change and nothing else.** A branch cut from a stale
  `main` drags everything that moved in between into the comparison, and the
  reviewer spends their attention telling the two apart.
- **CI runs against the code that will actually be merged.** Green on a
  three-week-old base says nothing about green on today's `main`; the failure
  then surfaces after the merge, where it is everybody's problem instead of
  mine.
- **Conflicts get resolved by whoever wrote the code**, while the reasons are
  still fresh, rather than by whoever hits the merge button.

**Rebase, never merge `main` into the branch.** A `Merge branch 'main' into …`
commit carries no information, and it makes the branch impossible to read as a
series of changes.

If the rebase conflicts, resolve it and **re-run the tests and the linters
before opening the PR** — a conflict resolution is fresh code that nothing has
checked yet. On a branch that was already pushed, force-push with
`--force-with-lease`, never a bare `--force`.

## A stacked PR is opened as a draft

**A PR whose base is another PR's branch — not `main` — is opened with
`--draft`**, and stays a draft until everything under it has merged:

```bash
gh pr create --draft --base <parent-branch> --head <branch> …
```

The reason is the merge button. On a stacked PR it merges into the *parent's
branch*, not into `main`: the change silently folds into the PR below it, which
then carries two changes under one title and one description. Draft status is
what makes that button unavailable while the stack is waiting.

A draft leaves the stack's dependency visible, and gets a normal review in the
meantime. Mark it ready only when its base is `main` again: the parent has
merged, the PR has been retargeted to `main`, and the branch has been rebased
onto it (see above; with squash merges, `git rebase --onto origin/main
<old-parent-tip>`, so the parent's pre-squash commits are dropped):

```bash
gh pr ready <number>
```

Only the bottom PR of a stack, the one based on `main`, is ever ready for
review. Say in each stacked PR's description which PR it sits on.

## Title and body

- **The title follows the repo's commit-subject style** (read
  `git log --oneline`): a squash merge makes it the commit subject on the
  default branch.
- **Link the issue it resolves** with `Closes #123` in the body, so the merge
  closes it. Never close an issue by hand on the user's behalf.
- **A follow-up spotted while opening the PR** goes in the body as
  `Follow-up: #123`, after the issue is opened (see
  `github-issue-conventions`) — never as a comment in the code.
- **A breaking change says what breaks, and how to migrate**, in the body — a
  removed or renamed API, CLI flag, env var, config key or chart value; a
  changed default, wire format or schema that needs a migration; a dropped
  platform or version. Anything that forces a user to change something to
  upgrade.

## Labels

**PR labels feed the generated release notes, so they follow
`.github/release.yaml`.** In a repo that has one, every PR carries its labels
from creation: an unlabelled PR lands in the "Other Changes" bucket and is
invisible to anyone scanning the changelog by category. **No `release.yaml`, no
label**: nothing reads them, so a category label there is noise on every PR.
That holds for `breaking` (the body already says what breaks) and for area
labels (the title's `area:` prefix already names the area). Bot PRs keep what
their config applies (see [Bot pull requests](#bot-pull-requests)).

## How GitHub actually sorts a PR

The generated notes put a PR in the **first category whose label set matches, in
the order the categories appear in `.github/release.yaml`** — one PR, one
section. Two consequences that drive every choice below:

- **Extra category labels are silently ignored, not additive.** A PR carrying
  both `feature` and `fix` shows up once, under whichever category comes first
  in the file. So pick the one that describes the change; don't hedge by
  applying two.
- **A PR that is genuinely two changes is two PRs.** If you cannot name one
  category without lying, split it rather than picking the bigger half.

## When the repo has `.github/release.yaml`

- **Pass `--label` on `gh pr create`** — do not open the PR first and label it
  later (you usually forget). Repeat the flag per label:
  ```bash
  gh pr create --base main --head <branch> \
    --title "…" --body "…" \
    --label feature --label rust
  ```
  If you genuinely opened a PR without labels, fix it immediately with
  `gh pr edit <number> --add-label <name> [--add-label <name>]`.
- **Read the repo's actual labels and its categories — never invent or guess
  names.** Both, before writing the command:
  ```bash
  gh label list --limit 100        # what exists
  cat .github/release.yaml         # what it maps to, and in which order

From leroyguillaume/claude, MIT.

More from leroyguillaume/claude