Grandfathered-Debt Gate¶
Category: Gate Pattern
Overview¶
A grandfathered-debt gate applies a limit from a chosen date forward while tolerating the violations that already existed. It is the pattern for a rule that is right but cannot be retrofitted in one proportionate change: a module length cap adopted against a codebase that already exceeds it, a type coverage threshold, a lint rule with a backlog. New violations fail; recorded ones may shrink but never grow.
Concepts¶
Recorded Measurement¶
The measured value of each existing violation on the date the gate was added, not a description of it. "It was 1191 lines on 260806" is a fact that stays checkable; "this file is too long" is an opinion that ages badly.
Three Checks¶
The gate needs all three to remain honest:
- New violations fail. Anything over the cap that is not recorded is a new violation.
- Recorded debt cannot grow. A recorded entry that exceeds its recorded value fails.
- Stale entries fail. A recorded entry that now passes the cap must be removed.
The third is the one most often left out and the one that keeps the list credible. After a module is split, a forgotten entry makes the debt look worse than it is, and a list known to be wrong stops being read.
Usage Guidelines¶
Use when:
- The rule is correct but the codebase already violates it in many places
- Fixing every violation in one change would be disproportionate or risky
- Progress should be ratcheted: improvement is permitted, regression is not
Avoid when:
- The violations are few enough to fix in the change that adopts the rule
- The measurement is unstable, so entries would need constant revision
- The limit is arbitrary and the list would grow rather than shrink
Implementation¶
from collections.abc import Mapping
class GrandfatheredLimit:
"""A cap that new code must meet and recorded violations may not exceed."""
def __init__(self, cap: int, recorded: Mapping[str, int], recorded_on: str) -> None:
self._cap = cap
self._recorded = dict(recorded)
self._recorded_on = recorded_on
def new_violations(self, measurements: Mapping[str, int]) -> list[str]:
"""Modules over the cap that were not recorded when it was adopted."""
return [
f"{name} measures {value}, over the cap of {self._cap}. "
f"Bring it under the cap; the allow list is closed."
for name, value in sorted(measurements.items())
if value > self._cap and name not in self._recorded
]
def worsened(self, measurements: Mapping[str, int]) -> list[str]:
"""Recorded modules that have grown since the cap was adopted."""
return [
f"{name} measured {self._recorded[name]} on {self._recorded_on} "
f"and now measures {value}. Recorded debt may shrink, not grow."
for name, value in sorted(measurements.items())
if name in self._recorded and value > self._recorded[name]
]
def stale_entries(self, measurements: Mapping[str, int]) -> list[str]:
"""Recorded modules that now pass the cap and should be removed."""
return [
f"{name} measures {measurements[name]} and now passes the cap of "
f"{self._cap}. Delete its entry so the list stays accurate."
for name in sorted(self._recorded)
if name in measurements and measurements[name] <= self._cap
]
def violations(self, measurements: Mapping[str, int]) -> list[str]:
"""Every violation across the three checks."""
return (
self.new_violations(measurements)
+ self.worsened(measurements)
+ self.stale_entries(measurements)
)
Usage¶
LIMIT = GrandfatheredLimit(
cap=666,
# Module -> its length when this gate was added. Lower a number when the
# module shrinks; delete the entry when it passes the cap.
recorded={"pkg/metadata_definitions.py": 1191, "pkg/importer/isa.py": 842},
recorded_on="260806",
)
assert not LIMIT.violations(measure_module_lengths())
Splitting the three checks into three tests reports the three failures separately, which matters because they call for different responses: shorten the module, revert the growth, or prune the list.
Trade-offs¶
Benefits:
- Allows adopting a correct rule without a large retrofit
- Ratchets in one direction, so the debt is bounded and decreasing
- Records measured facts with dates, which stay checkable as the code changes
Drawbacks:
- The allow list is a second thing to maintain and can be extended under pressure
- Measurements are noisy for some metrics, causing failures unrelated to the rule
- Tolerated violations can persist indefinitely if nothing schedules the work
Real-World Examples¶
- Module or file length caps adopted against an existing codebase
- Type checker strictness raised per module with a shrinking exclusion list
- Lint rules enabled with a baseline file of pre-existing findings
Related Patterns¶
- Boundary Gate uses a similar list, but separates principle from debt
- Absence Gate records a decision where this records a measurement
- Population Gate bounds a count rather than a per-item measurement
API Reference¶
design_patterns.gates.grandfathered_debt
¶
Grandfathered-Debt Gate: apply a limit forward over existing violations.
This is the pattern for a rule that is right but cannot be retrofitted in one proportionate change. New violations fail; recorded ones may shrink but never grow; and entries that now pass the cap must be deleted, which is the check most often left out and the one that keeps the list credible. After a module is split, a forgotten entry makes the debt look worse than it is, and a list known to be wrong stops being read.
Entries record a measured value and a date. "It was 1191 on 260806" is a fact that stays checkable; "this file is too long" is an opinion that ages badly.
GrandfatheredLimit
¶
A cap that new code must meet and recorded violations may not exceed.
Example
Source code in src/design_patterns/gates/grandfathered_debt.py
17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 | |
__init__(cap, recorded, recorded_on)
¶
Adopt a limit over a codebase that already violates it.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
cap
|
int
|
The largest permitted measurement. |
required |
recorded
|
Mapping[str, int]
|
Existing violations mapped to their measured value on the day the limit was adopted. |
required |
recorded_on
|
str
|
That date, in YYMMDD format. |
required |
Source code in src/design_patterns/gates/grandfathered_debt.py
check(measurements)
¶
Assert that the codebase is within the ratchet.
Splitting the three checks into three separate tests is usually better, because the three failures call for different responses: shorten the module, revert the growth, or prune the list.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
measurements
|
Mapping[str, int]
|
Current measurement per module. |
required |
Raises:
| Type | Description |
|---|---|
AssertionError
|
If any of the three checks finds a violation. |
Source code in src/design_patterns/gates/grandfathered_debt.py
new_violations(measurements)
¶
Find modules over the cap that were not recorded at adoption.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
measurements
|
Mapping[str, int]
|
Current measurement per module. |
required |
Returns:
| Type | Description |
|---|---|
list[str]
|
list[str]: One message per new violation, ordered by module name. |
Source code in src/design_patterns/gates/grandfathered_debt.py
stale_entries(measurements)
¶
Find recorded modules that now pass the cap.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
measurements
|
Mapping[str, int]
|
Current measurement per module. Modules absent from this mapping say nothing about their entry and are skipped. |
required |
Returns:
| Type | Description |
|---|---|
list[str]
|
list[str]: One message per entry that should be deleted. |
Source code in src/design_patterns/gates/grandfathered_debt.py
violations(measurements)
¶
Run all three checks.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
measurements
|
Mapping[str, int]
|
Current measurement per module. |
required |
Returns:
| Type | Description |
|---|---|
list[str]
|
list[str]: New violations, then regressions, then stale entries. |
Source code in src/design_patterns/gates/grandfathered_debt.py
worsened(measurements)
¶
Find recorded modules that have grown since adoption.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
measurements
|
Mapping[str, int]
|
Current measurement per module. |
required |
Returns:
| Type | Description |
|---|---|
list[str]
|
list[str]: One message per regression, quoting the recorded value and the date it was measured. |