Overview

Trunk-based development trades release isolation for a lower merge-conflict cost -- integrating small, frequent changes to trunk means conflicts are caught and resolved while they're still small. The right choice depends on team size and release cadence, not fashion or trend.

<type>[optional scope]: <description>, e.g. fix(parser): handle empty input. A breaking change is signaled either by a ! right after the type/scope (feat(api)!: drop v1 endpoint) or by a BREAKING CHANGE: footer -- either one independently marks the commit as breaking.

PATCH, MINOR, and MAJOR, respectively -- SemVer's MAJOR.MINOR.PATCH scheme ties the bump directly to the kind of change: incompatible (MAJOR), backward-compatible addition (MINOR), or backward-compatible fix (PATCH).

Added, Changed, Deprecated, Removed, Fixed, Security. Every new entry lives under an ## [Unreleased] heading until a tagged release moves the whole section under a dated version heading.

Name whether it's blocking or a nit, so the author knows what must be resolved before merge versus what's optional, and stay prompt and respectful of the author -- feedback aimed at the code, never the person.

Roughly ~100 lines is reasonable, ~1000 too large -- a non-absolute guideline, not a hard rule. Scoping to one concern lets a reviewer state the PR's single purpose in one sentence and review it faster, more thoroughly, and roll it back more safely if it turns out to be wrong.

gh pr create opens a new pull request from the terminal; gh pr review (with --approve, --request-changes, or --comment) posts a review; gh pr view (with --comments or --json) inspects a PR's state and comment history -- together they close the review loop without ever leaving the CLI.

Lint, then test, then build -- gated (each stage only runs if the previous one succeeded), and ordered cheapest-and-fastest first so a failure is caught and stops the pipeline as early and cheaply as possible, before the most expensive stage ever runs.

A required check blocks a merge on failure -- reserved for whatever actually protects production. A lower-value check (a style nit, for example) should demote to a warning rather than block, so gates protect what matters without ossifying into pure ceremony that blocks merges over trivia.

.pre-commit-config.yaml. It catches a class of defect -- trailing whitespace, a lint violation, an unformatted file -- locally, before the commit ever completes or reaches CI, which is cheaper and faster feedback than waiting for the same defect to fail a CI run minutes later.

Many fast (unit) tests at the base, fewer slow (integration/e2e) tests toward the top. A reviewer should name the skew explicitly when a change adds a disproportionate number of slow tests relative to fast ones, flagging it as a design choice worth discussing, not silently approving it.

A proxy for testedness -- how much code a test suite executes -- not proof of correctness. Turning it into a hard target (e.g. "100% coverage required to merge") invites assertion-free tests written purely to execute lines and satisfy the number, a textbook Goodhart's-law failure.

Hypothesize, change one thing, observe -- a disciplined loop applied before reaching for a fix, rather than guessing and patching. git bisect adds a way to halve an unknown regression's search space with each step, turning a linear scan through dozens of commits into a logarithmic number of test runs.

Continuous small refactors, folded into ordinary feature work, beat a deferred big-bang rewrite on both risk (a small refactor is easy to verify and revert; a month-long rewrite risks losing behavior nobody remembered to re-test) and cost (small, frequent changes stay cheap; a deferred rewrite accumulates cost and risk the longer it waits).

A tiny, incidental improvement -- rename one poorly-named variable you happen to touch while fixing an unrelated bug, nothing more. Keeping it tiny (and often its own small commit) keeps the change reviewable and prevents an unrelated, sprawling rewrite from hiding inside what should be a focused fix.

The shortcut's Fowler quadrant (prudent/reckless x deliberate/inadvertent) and a named owner -- naming the quadrant and owner keeps the debt a visible, prioritizable backlog item instead of a silent tax nobody is accountable for paying down.

Colocated with the code it describes, versioned in the same repository, and reviewed in the same PR that changes the behavior it documents -- all three together resist the drift a separate wiki, updated on its own schedule (or never), invites.

Is it hard to reverse, and is it architecturally significant? Both questions must pass -- a hard-to-reverse but purely cosmetic change, or an easily reversible architectural experiment, does not earn one; only a change that is both hard to reverse AND changes the system's own structure does.

A precision that does not exist -- an hour figure looks confident without the team actually having grounds for that confidence this early. #NoEstimates does not ban estimating outright; it asks whether some decisions (prioritization, forecasting) can be made well without an estimate step at all, e.g. by slicing work smaller and counting throughput instead.

Solo throughput -- two or more people working one problem is slower in raw output than each working separately. In return it buys shared context and fewer defects, a trade worth making for high-risk or unfamiliar work where the cost of a defect or of siloed knowledge outweighs the throughput lost.

When work actually counts as finished -- an explicit, shared checklist (tests pass, docs updated, reviewed) gates that moment, per the Scrum Guide's framing, rather than "finished" meaning something different to whoever happens to be asked.

It decouples deploy from release -- code merges to trunk disabled, shippable at any time, and gets turned on independently of when it was deployed, which is exactly what enables trunk-based development (co-01) in the first place. Other categories: an ops toggle (a kill switch, a short operational lifespan), an experiment toggle (an A/B test, lives until the experiment concludes), or a permission toggle (long-lived, gates a feature by user segment).

Detect, then mitigate, then root-cause -- restore service before fully understanding why it broke. The write-up must use blameless, actor-neutral language that traces the cause to a systemic gap (a missing guard, an untested assumption), never to an individual's mistake.

The 4-person startup: trunk-based -- frequent shipping and a small team make integration-conflict cost the dominant risk, and there's no external release-isolation requirement to trade against it. The 12-person team: a longer-lived branching model fits better -- the quarterly, regulator-tied release train genuinely needs release isolation, and a larger team can absorb the coordination cost of longer-lived branches more easily than it can absorb shipping uncertified work (co-01).

MAJOR. Even though two of the three commits alone would only justify PATCH and MINOR, the third commit's ! marker signals a breaking change, and SemVer's rule is that the bump matches the HIGHEST-severity change present in the release, not an average or a majority vote (co-02, co-03).

Split into two PRs. The payments retry change and the README typo fix are two unrelated concerns bundled into one diff -- co-06 requires a PR scoped to one concern, and a reviewer approving the payments logic has no clean way to separately evaluate (or, if needed, revert) the incidental typo fix. The typo fix alone is small enough to ship as its own trivial PR or a tiny follow-up commit.

The repository's own pytest suite should be required -- it directly protects this codebase's correctness. The flaky third-party smoke test should demote to a warning: co-09 reserves merge-blocking status for a check that actually protects production, and a check that fails ~5% of the time for reasons outside this repository's control would otherwise routinely block unrelated, correct changes.

The import-ordering comment is a nit -- optional, stylistic, safe to merge without addressing. The empty-list comment is blocking -- it describes a real production crash, and per co-05, an author needs to know from the comment itself which one must be resolved before merge and which one can be deferred or ignored without holding up the PR.

This is co-12's exact failure mode -- the coverage tool only measures whether a line EXECUTED, not whether its behavior was actually checked. A test with no assertion at all can hit every line apply_discount() has and report near-100% coverage while verifying literally nothing about correctness; the high number is measuring the wrong thing entirely.

Yes, git bisect is still the right tool -- ceil(log2(60)) = 6 steps versus up to 60 for a one-at-a-time scan. The intermittency changes HOW each step is judged: a single test run per commit is not reliable evidence at a ~20% false-negative rate, so each bisect step should run the reproduction check several times (or use git bisect run with a script that retries and reports "bad" only on a majority of failing runs) before marking a commit good or bad (co-13).

This violates co-15's boy-scout-rule scope -- a boy-scout cleanup is meant to stay a tiny, incidental improvement to code you're already touching, not a 180-line drive-by rewrite riding along with an unrelated one-line fix. It also violates co-06's PR-hygiene rule: bundling the fix and the rewrite makes the actual crash fix harder to review and impossible to revert independently of the cosmetic changes. The fix: ship the one-line crash fix alone; propose the broader cleanup as its own separate PR if it's worth doing at all.

(2) first, (3) or (1) after. Co-16's prioritization rule ranks by ONGOING FRICTION, not recency -- item (2) is the oldest of the three but has caused three actual production incidents, which is concrete, recurring, measurable cost. Item (1) is recent and has caused zero known problems on a rarely-changed module -- low ongoing friction regardless of freshness. Item (3) has no described impact at all and should be clarified (or dropped) before it can be ranked meaningfully.

Only (a). Applying co-18's two-question test: (b) is trivially reversible (revert one line) and not architecturally significant. (c) LOOKS more consequential than (b), but a polling-interval config value is also a single-line, instantly reversible change with no structural impact on the system. (a) fails both tests in the ADR-earning direction -- swapping the message queue technology touches every producer and consumer, is expensive to undo once consumers depend on the new queue's semantics, and changes the system's own messaging architecture.

Push back on the hour figure specifically, per co-19 -- an hour estimate for unfamiliar, poorly-scoped work fakes a precision the team cannot actually have yet. A better response proposes a #NoEstimates-style alternative: spend a short, timeboxed spike to reduce the unknowns first, then slice the integration into small, independently shippable pieces and track actual throughput instead of committing to a specific hour figure up front.

The CRUD endpoint: solo -- well-understood, low-risk, low-novelty work where pairing's throughput cost isn't justified by a defect or knowledge-sharing benefit that's unlikely to matter here. The unfamiliar payment integration: pairing (or mobbing if the risk is high enough) -- unfamiliar, higher-risk work is exactly where co-20's trade of solo throughput for shared context and fewer defects pays off, especially since nobody on the team currently holds this knowledge alone.

Not necessarily "done-done." Per co-21, "done" typically means the code is merged and passing its checks; "done-done" additionally means it's deployed AND observed to be behaving correctly in production (monitored). A team's Definition of Done should state explicitly which of the two a given checklist item is asking for -- "merged" and "verified working in production" are two different claims, and conflating them is how a merged-but-unmonitored regression slips through unnoticed.

(a) is a release toggle -- exactly co-22's release/deploy decoupling use case, ships to trunk disabled and flips on at launch. (b) is an ops toggle (a kill switch) -- a short-lived, operationally triggered flag meant to be flipped instantly during an incident, not tied to a planned launch date.

Yes -- detect (14:02), mitigate (14:04, the restart, which restores service quickly without yet understanding WHY), then root-cause (14:35), then a permanent fix (15:10). This is the correct order: service was restored in two minutes without waiting 33 more minutes to first understand the root cause, which is exactly the sequencing co-23 prescribes -- mitigate first, investigate after service is already restored.

A review step -- co-07's PR workflow closes the loop with gh pr create, gh pr review (request-changes or approve), and gh pr view, but this transcript jumps straight from creating the PR to merging it with no review command at all. Merging with no recorded review also violates co-05's review-etiquette expectation that a change gets reviewed before it lands, not just opened and self-merged.

"Improved" is not one of Keep a Changelog's six fixed categories (Added, Changed, Deprecated, Removed, Fixed, Security) -- co-04 requires exactly one of those six. A performance change to existing behavior maps to Changed, and the bullet itself should also name the specific, verifiable change ("now streams large payloads instead of buffering them fully") rather than a vague "faster" claim with no verifiable detail.

Wire it as a required CI check too, not local-only. Local hooks (co-10) catch most violations before a commit, but nothing forces every contributor to actually run pre-commit install (a one-time, easy-to-skip step, per Drill 5 below) or to keep their local hook versions current; a required CI check (co-09) is the backstop that guarantees the SAME rules apply uniformly, whether or not any individual engineer's local setup is current.

The test-pyramid shape (co-11) -- fifteen new slow, database-backed tests with no new fast unit tests inverts the "many fast, few slow" shape the pyramid recommends. A reviewer should name this explicitly and ask which of the fifteen could be rewritten as fast unit tests against the underlying logic directly, reserving the genuinely-needs-a-real-database cases for the smaller set of integration tests that actually require one.

After:

$ git add parser.py
$ git commit -m "fix(parser): handle empty input without crashing"
[main 4a1c9de] fix(parser): handle empty input without crashing
 1 file changed, 3 insertions(+), 1 deletion(-)
$ git log -1 --pretty=%s
fix(parser): handle empty input without crashing

Root cause: the before message has no type(scope): description structure at all -- co-02 requires a leading type token (fix, feat, and so on), an optional parenthesized scope, and a colon before the description. Tooling that derives a SemVer bump or a changelog entry directly from commit history (co-02, co-03, co-04) has nothing to parse from the before message; the after message both documents intent for a human AND stays machine-parseable.

After:

$ gh pr close 88 --comment "reopening against the correct base"
$ gh pr create --title "fix(gateway): add retry with exponential backoff" \
    --body "What: retries a failed upstream call up to 3 times with exponential backoff.
Why: a transient 503 was previously surfaced straight to the caller with no retry.
How verified: new unit tests in test_retry.py, all green." \
    --base main
Creating pull request for feature/rate-limit-retry into main in acme/api-gateway
 
https://github.com/acme/api-gateway/pull/89
{
  "baseRefName": "main",
  "number": 89,
  "title": "fix(gateway): add retry with exponential backoff"
}

Root cause: two separate violations stacked in one transcript -- --base develop targets a branch that isn't this trunk-based team's actual integration branch (co-01), so the PR would never land where CI and teammates expect it to; and an empty --body gives a reviewer no what/why/ how-verified to start from (co-06). The fix retargets the real trunk (main) and fills in a real description.

After:

$ git bisect start
$ git bisect bad HEAD
$ git bisect good main
Bisecting: 18 revisions left to test after this (roughly 5 steps)
[c481aa2] chore: unrelated change 19
$ python3 -m pytest -q test_totals.py && git bisect good || git bisect bad
Bisecting: 9 revisions left to test after this (roughly 4 steps)
...
# converges in ceil(log2(37)) = 6 steps, not up to 37

Root cause: a one-at-a-time linear scan costs up to 37 test runs in the worst case; git bisect halves the remaining search space on every step, converging in ceil(log2(37)) = 6 steps (co-13) -- the same regression, an order of magnitude fewer test runs, because bisection is the correct tool for "which of N commits introduced this," not a manual walk through every candidate.

After:

name: ci
on: [pull_request]
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - run: ruff check .
  test:
    needs: lint
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - run: pytest -q
  build:
    needs: test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - run: python -m build

Root cause: without needs:, all three jobs launch in parallel the instant the workflow triggers -- build runs (and burns compute) even when lint has already failed, exactly the expensive-stage-runs-anyway problem co-08 warns against. Adding needs: lint to test and needs: test to build makes each stage genuinely GATED, not merely listed in the same file, so a lint failure now stops the pipeline before test or build ever start -- also protecting co-09's required-check guarantee, since a required check on build alone would otherwise never even see the lint failure.

After:

$ pre-commit install
pre-commit installed at .git/hooks/pre-commit
$ printf 'bad_var = 1   \n' > sloppy.py
$ git add sloppy.py
$ git commit -m "chore: add sloppy module"
trim trailing whitespace.................................................Failed
- files were modified by this hook
$ git add sloppy.py
$ git commit -m "chore: add sloppy module"
trim trailing whitespace.................................................Passed
[main a71f204] chore: add sloppy module
 1 file changed, 1 insertion(+)

Root cause: .pre-commit-config.yaml merely declares which hooks to run -- co-10 requires a separate, one-time pre-commit install step to actually wire .git/hooks/pre-commit to invoke the framework. A config file sitting in the repo with no install step is inert, which is exactly why sloppy.py's trailing whitespace made it straight into the before transcript's commit; the fix runs the install step once, after which every future commit runs the hooks automatically.

After:

## [Unreleased]
 
### Changed
 
- `Client.fetch()` now streams large payloads instead of buffering them fully in memory.
 
### Fixed
 
- `Client.fetch(timeout=-1)` now raises `ValueError` at call time instead of hanging indefinitely.

Root cause: "Improved" and "Bugs" are not among Keep a Changelog 1.1.0's six fixed categories (Added, Changed, Deprecated, Removed, Fixed, Security) -- co-04 requires every entry to use exactly one of the six. "Improved" maps to Changed (existing behavior altered, not new); "Bugs" maps to Fixed. The rewrite also tightens each bullet to state the specific, verifiable change rather than a vague performance claim with nothing to check it against.

After: no ADR at all -- the rename ships as a single, self-explanatory commit:

git commit -m "refactor(billing): rename calc_tot to calculate_total for readability"

Root cause: co-18's two-question test -- hard to reverse, AND architecturally significant -- fails on both counts here. A rename is a single-commit (or IDE-rename-tool) revert, and it changes nothing about the system's structure. Writing an ADR for it does the opposite of an ADR's job: it buries the genuinely significant decisions (a database swap, a new consistency model) in noise, exactly the failure mode the ADR-trigger-decision worked example warns against. A clear commit message is the entire "decision record" a change this small ever needs.

After:

Debt: discount-calculation path (checkout/discounts.py) has unit tests only, no
integration coverage against the real pricing service.
Quadrant: prudent + deliberate (Fowler) -- a conscious, reasoned trade-off made
under a real deadline, not a mistake.
Owner: @priya
Mitigation: add integration tests against a pricing-service test double before the
next feature touches this path; tracked as ISSUE-482.

Root cause: "TODO: add tests later" with no owner and no named quadrant is exactly the silent-tax failure mode co-16 warns about -- a TODO with no owner competes with every other priority and reliably loses. Naming the quadrant (prudent/deliberate, not reckless/inadvertent) also matters: it records that this was a reasoned trade-off under real deadline pressure, not a mistake, which changes how a future reader should weigh paying it down.

After:

A hotfix was pushed directly to main, bypassing the CI pipeline, shipping an
unformatted, untested change that broke the build for the rest of the team for 20
minutes. The repository's branch protection did not require the lint-test-build
pipeline to pass before a push to main could land -- any push, by any team member,
on any day, could equally have bypassed it.
 
Fix: branch protection on main now requires the lint-test-build pipeline (co-08) to
pass before any push (including a hotfix) can land, no exceptions (shipped same
day).

Root cause: "Jordan should have run the pipeline" attributes a systemic gap -- no branch protection actually enforcing the required check (co-09) -- to an individual's judgment call under pressure. Naming the actual gap both satisfies co-23's actor-neutral rule AND produces a fix (turn on required-check branch protection) that prevents the SAME failure for every future team member, not just a request that Jordan personally be more careful next time.

After (split into three PRs, one shown):

What: fixes test_checkout_flow's flaky assertion by waiting on the actual async
callback instead of a fixed sleep.
Why: the test failed intermittently in CI (roughly 1 in 20 runs) because a 200ms
sleep sometimes wasn't long enough on a loaded runner.
How verified: reran the fixed test 50 times locally with no failures; CI green.
Where to look first: test_checkout_flow.py's new await_callback() helper -- the
only file with new logic.

Root cause: "all three were sitting in my branch already" is not a scoping rationale -- co-06 requires a PR scoped to ONE concern, and bundling a flaky-test fix, an unrelated refactor, and a dependency bump means none of the three can be reviewed, approved, or reverted independently if only one turns out to be wrong. Splitting into three PRs (one shown) also lets each description state a genuine why and a where-to-look-first, instead of one vague, shared justification covering all three unrelated changes.

Every gate -- review, CI, required coverage -- trades throughput for safety. Maxing it everywhere treats a solo throwaway prototype the same as a shared production system, which is pure drag on the former and doesn't even guarantee safety on the latter if the ceremony is generic rather than targeted. Pragmatism here means calibration: dial the strictness of review/CI/coverage to what's actually at stake if the change breaks, not applying one fixed policy regardless of context -- the same discipline the Tensions section names directly ("the skill is dialing ceremony to the blast radius, not maxing or zeroing it").

Goodhart's law: the moment a measure becomes a target, it stops being a good measure. A developer under deadline pressure facing "100% coverage or the PR is blocked" has a direct incentive to write a test that executes every line without asserting anything meaningful, because the merge gate rewards the number, not the testedness the number was originally supposed to proxy for -- exactly the assertion-free-test failure mode co-12's worked example demonstrates directly.

Because the right answer genuinely depends on context -- team size, release cadence, and review culture -- not on which model happens to be fashionable. Trunk-based optimizes integration frequency and small diffs at the cost of needing feature flags to hide incomplete work; GitFlow optimizes release isolation at the cost of merge hell as branches age. Pragmatism means picking based on the team's actual coordination shape, which is exactly why AS1 above reaches two different answers for two differently-shaped teams instead of one universal rule.

Bisect halves an unknown regression's search space, but it only tells you WHICH commit broke something, not WHY -- the hypothesize-then-verify loop is still required to actually understand and fix the root cause once bisect narrows it down. Reaching for bisect without first framing what you'd expect to find turns a disciplined debugging practice into blind commit-flipping; the tool is pragmatic exactly because it's paired with a hypothesis at each step, not a replacement for having one.

Every long-lived branch is a form of coupling -- two developers' in-flight work can silently drift out of sync the longer both branches live before merging, the same way two tightly coupled modules can't change independently without breaking each other. Trunk-based development with small, frequent merges keeps that coupling window short, the same way a clean module boundary keeps a compile-time dependency narrow; both trade some short-term convenience (working in isolation, deferring integration) for keeping the actual coupling small and cheap to resolve.

A PR bundling three unrelated concerns -- a bug fix, an unrelated refactor, a dependency bump -- is low-cohesion in the same sense a class doing three unrelated things is: reviewing it, reverting it, or bisecting a future regression to it all become harder, because the unrelated concerns can't be evaluated or rolled back independently. Scoping to one concern is the change-management equivalent of decomposing a low-cohesion module into focused ones -- Drill 10 above shows exactly this failure and its fix.

Without a flag, "merge to trunk" and "customers see this feature" are the SAME event, tightly coupled -- you cannot do one without the other. A flag breaks that coupling into two independently controllable events: code can merge (and be tested in trunk) long before it's turned on for anyone, and it can be turned off again (an ops toggle) without a redeploy. That's exactly what makes trunk-based development viable for incomplete work in the first place -- the flag is the coupling-breaking mechanism co-01 depends on, not a nice-to-have.

Name the specific failure mode the practice actually prevents -- CI prevents the integration hell of big-bang merges; conventional commits and trunk-based dev prevent the review-and-conflict cost long-lived branches produced at scale; blameless postmortems prevent people hiding incidents out of fear of blame -- and ask whether your context is actually exposed to that failure. A practice adopted "because it's standard" without that check is exactly the over-ceremony the Tensions section warns a solo prototype doesn't need; the lineage test is what turns "always do X" into "do X because of the specific thing it protects against."