# Patch Submission

> patch-submission — thin wrapper for the upstream mail

- Skill: `matejformanek/patch-submission` (Agent Skill)
- Install (CLI): `npx skillmds@latest add matejformanek/patch-submission`
- Raw SKILL.md: https://api.skillmd.com/api/skills/matejformanek/patch-submission/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: matejformanek (https://skillmd.com/u/matejformanek)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/matejformanek/patch-submission

---


# patch-submission — thin wrapper for the upstream mail

This skill is the **mechanics** of sending a PG patch upstream:
format-patch, cover letter, CF entry, review-cycle bookkeeping. The
**review content** (build, tests, design fit, completeness, style) lives
in two other skills:

- **`pg-patch-review --self`** — runs the 5-critic fan-out + Phase 0
  reflex gates + REJECT-track decision against your own diff. Run this
  BEFORE format-patching. Any blocking finding = stop, fix, re-run.
- **`commit-message-style`** — the upstream PG commit-message format
  (no `Co-Authored-By`, imperative title, Author / Reviewed-by /
  Discussion / Backpatch-through trailer block).

Don't re-derive their rules here.

## Method — six steps

### 1. Self-review gate (REQUIRED first)

Run `pg-patch-review` in `--self` mode against the local branch.

- Stage 3 returns Ready-for-Committer → proceed to step 2.
- Waiting-on-Author / Needs-info / REJECT-A/B → fix and re-run.
- REJECT-C → escalate to user (your verdict probably needs revision).

### 2. Rebase onto current upstream master

```bash
git fetch origin && git rebase origin/master
git log --oneline master..HEAD             # confirm the series
git diff --check master..HEAD              # whitespace clean
```

A v(N) that doesn't apply against current master is the most common
reason a CF entry gets bounced back without review.

Confirm the pre-commit hook is installed
(`grep -q 'pg-precommit-guard' dev/.git/hooks/pre-commit`); if so,
`pgindent` already ran against every commit in the series and no
separate pre-format step is needed before `format-patch`.

### 3. Format-patch the series

```bash
git format-patch -v1 master..HEAD          # first send
git format-patch -v3 master..HEAD          # nth re-submission
```

Filenames: `vN-NNNN-<subject>.patch`. Verify each commit message
follows `commit-message-style` before generating the patches; the
subject line of each patch becomes the email subject.

### 4. Compose the cover email

Send to **pgsql-hackers@lists.postgresql.org**, **plain text only**,
patches as attachments (not inline). Body covers:

- One-paragraph summary of the problem.
- One paragraph on the solution / why this approach.
- Target branch (`master`).
- Confirmation it builds + `ninja test` passes.
- Platforms tested.
- Performance notes if relevant.
- Link to prior discussion via `https://postgr.es/m/<message-id>`.
- Tag: **WIP** (want shape feedback) or **ready for review**.

If replying to an existing thread (v(N+1)), **reply** — don't start a
new thread.

### 5. Register the CommitFest entry

After sending, go to <https://commitfest.postgresql.org/> and add an
entry to the **open** CF:

- Title (mirror the patch subject).
- Authors.
- Target version (`master` / next major).
- Topic — pick the closest backend subsystem.
- Thread Message-Id (URL of your -hackers post on
  `https://www.postgresql.org/message-id/<id>`).

Then **review at least one other patch** in the same CF — the
bartering norm. Skipping it is noticed.

### 6. Review-cycle loop

When a reviewer responds, CF flips to **Waiting on Author**:

1. Address every point. For disagreements, explain in the reply
   rather than silently ignoring.
2. **Fold fixes into the right logical commit via `git rebase -i
   master`** — don't ship a "fix review comments" commit on top. v(N+1)
   should be a clean rewrite of v(N) with the asks applied.
3. Re-run `pg-patch-review --self` against the rebased branch.
4. `git format-patch -v<N+1>` + reply on the same thread.
5. Flip CF entry back to **Needs Review**.

## Email anti-checklist (will get the patch bounced)

- HTML email — never. Plain text only.
- Top-posted reply — never. Reply inline under quoted lines.
- Patch pasted into email body instead of attached.
- Patch that doesn't apply cleanly to current master.
- Corporate confidentiality footer.

The `pg-patch-review --self` step covers test / doc / catversion gaps;
not duplicated here.

## After commit

The committer runs pgindent / pgperltidy, writes the final commit
message with `Author:` / `Reviewed-by:` / `Discussion:` trailers,
decides on backpatch (bug fixes only — see versioning policy), and
commits. Your CF entry flips to **Committed**. Done.

## Cross-references

- `.claude/skills/pg-patch-review/SKILL.md` — `--self` mode for the review content this skill no longer duplicates.
- `.claude/skills/review-checklist/SKILL.md` — eight-phase scaffold (Phase 0 REJECT-track + reflex gates) that `pg-patch-review --self` invokes.
- `.claude/skills/commit-message-style/SKILL.md` — upstream PG format for the per-commit messages this skill format-patches.
- `.claude/skills/coding-style/SKILL.md` — pgindent + warnings check that the self-review walks.
- `.claude/skills/testing/SKILL.md` — `make check` / `ninja test` flavor selection.
- `knowledge/community/patch-workflow.md` — long-form workflow reference.
- `knowledge/community/review-patterns.md` — how reviewer comments are structured (so you can address them well).
- [wiki: Submitting a Patch](https://wiki.postgresql.org/wiki/Submitting_a_Patch)
- [wiki: CommitFest](https://wiki.postgresql.org/wiki/CommitFest)