Match The House Shape

Match the house shape (what merges, not what's documented)

Purpose

The reviewer who will read your PR has a shape in their head — and it was set by the hundreds of PRs they have already merged, not by the words in CONTRIBUTING.md. A change that arrives in that familiar shape (roughly the median churn, the usual file-count, the expected title prefix, tests where tests usually go) is cheaper to hold in the head and cheaper to sign off. A change that arrives three times the usual size, spread across ten files, with no JIRA key in the title, costs the reviewer extra work before they can even start — and that cost is what stalls it.

The honest framing is review cost, not correctness: matching the house's usual shape makes your PR cheaper to review, which helps it land as help. It does not make a wrong change right, and being small is not a virtue in itself. This is about fitting the house so the reviewer's attention goes to the change, not to its packaging.

When to use

• After you have picked the work and before you shape the PR — to decide how big, how many files, what the title looks like, whether to include tests.
• When a change feels large and you are unsure whether to split it.
• On a repo new to you, to learn its real conventions from data instead of docs.

When NOT to use

For when to talk to maintainers before coding, that is discuss-in-issue-first; this skill governs the shape of what you submit, not the timing of the conversation.

The practice (checklist)

• Query recently merged PRs: gh pr list --repo <r> --state merged --limit 200 --json additions,deletions,changedFiles,title,createdAt,mergedAt,files
• Compute the median churn (add+del), median changed-files, the title-prefix convention (e.g. share starting with a JIRA key), the test-touch rate, and the median days-to-merge.
• Compare your candidate PR to that median on each axis.
• If you are well above the median churn or file-count, split the work or scope it down until it fits.
• Adopt the title convention (for Solr, prefix with the JIRA key).
• Include tests if the house's merged PRs usually touch tests.

Rationalizations

RECEIPT

Corpus measurement (local mirror of apache/solr PRs; observational). Computed over 3,510 MERGED apache/solr PRs by tools/house-shape.py, the median shape of what merges:

Churn distribution: ≤10 LOC — 815 PRs; 11–50 — 843; 51–200 — 871; 201–1000 — 716; 1000+ — 265.

Reproduce it yourself — the mirror command is in the tool's docstring, and its output feeds the tool directly (both gh's camelCase and the REST API's snake_case are read). Run it against any house to get that house's numbers instead of Solr's; the corpus isn't shipped because it's large and repo-specific. Don't take the table above on faith — a 12-PR slice of recent Solr merges lands at +54/−6, 5 files, 58.3% JIRA-key titles, 3.2 d, so a small sample reads noisier but in the same place.

Honesty labels (this is a correlation, not a proven lever):

• Shape of what merged. This describes the shape the house actually merges; it is a CORRELATION, not proof that matching it CAUSES a merge.
• Confound. Bigger changes are both harder to review AND more likely to be genuinely complex or contested. A right-sized PR lowers review cost, but it does not make a wrong change right — the same discipline as discuss-in-issue-first's "faster, not more often".
• Don't over-claim "smaller is always better". The mid-range buckets are fairly even (843–871 across 11–200 LOC); only the 1000+ tail (265 PRs) is where being oversized clearly bites.

Lifecycle

• Signals it worked: review focuses on the change itself, not on its size or packaging; no "please split this" or "add the JIRA key" round-trip; time-to-first- review in line with the house median.
• What to log on a misfire: a PR that fit the revealed shape but still stalled on size/packaging, or a house where the median mispredicted the reviewer's ask. Record it in LEDGER.md.
• Death criterion: retire for a repo if its merged-PR shape can't be queried, or if the house explicitly documents a different expected shape than it actually merges (follow the documented one there).
• Relates to: pairs with discuss-in-issue-first — that one is when to talk, this one is what shape to submit. Both are "fit the house".