Skip to content

docs(adr): compress to 3 records in the domain-modeling format - #81

Merged
lesnik512 merged 1 commit into
mainfrom
docs/compress-adrs
Sep 19, 2026
Merged

lesnik512 merged 1 commit into
mainfrom
docs/compress-adrs

Conversation

@lesnik512

Copy link
Copy Markdown
Member

Rewrites docs/adr/ from 4 records (~1,460 words) to 3 (~470 words), one paragraph each, in the
shape the domain-modeling ADR format asks for. The **Decision:** line, the ## Context and
## Decision & rationale headings and the **Revisit trigger:** section are gone; a revisit
trigger survives only where it is the real boundary of the decision. Survivors keep their original
relative order and are renumbered 0001-0003.

Evaluation

Each record was tested against the admission test: hard to reverse, surprising without context, the
result of a real trade-off. A record that fails on its own but states a rule a survivor relies on
was folded into that survivor as a sentence.

Old Outcome New Reason
0001 fake broker keeps immediate delivery kept 0001 Breaking change to a public testing API, and a reader who sees _patch_broker mocking the Redis client will propose the in-memory store that was already rejected.
0002 keep construction factories dropped - Fails the test on two counts: inlining two pure constructor-bundling functions is the cheapest possible reversal, and the record decides not to do a cleanup rather than choosing between alternatives. Its rule, that the package mirrors FastStream's own Redis broker layout, is folded into the new 0002 as one sentence.
0003 no per-call middlewares= kwarg kept, renumbered 0002 A removed public kwarg with a deliberate hard break, and both rejected alternatives (silent broker-scope routing, a local re-implementation) are non-obvious.
0004 typing-extensions over version-gated imports kept, renumbered 0003 A declared runtime dependency plus an unconditional typing_extensions import that looks redundant on 3.13; the version gate and dropping @override were both real options.

No merges: the three survivors are about different boundaries.

Citations

Only two existed. docs/agents/domain.md names 0002-keep-construction-factories.md in its
file-structure example, now 0002-no-per-call-middlewares-kwarg.md, and cites ADR-0001 in the
conflict-flagging example, whose number is unchanged but whose parenthetical title was updated to
match the rewritten record. The intra-ADR [ADR-0001](0001-fake-broker-keeps-immediate-delivery.md)
link lived in the dropped record and went with it. No Python cites an ADR. The repo-wide sweep finds
no reference to an old or dropped number.

Stale claims

None. Every concrete claim was re-checked against the code and all of them still hold:
FakeTimersProducer.publish encodes through TimerMessageFormat.encode and calls
process_message directly, TestTimersBroker._patch_broker stubs zrangebyscore/zscore/the
cancel_all pipeline, scheduled_timers exists, TimerStore is a concrete class with no
Protocol and no in-memory sibling, the subscriber's default polling_interval is still 0.05,
neither TimersRegistrator.subscriber()/.publisher() nor TimersRoute/TimersRoutePublisher
takes middlewares= while TimersBroker/TimersRouter still do, RedisClient is a
typing.TypeAlias, override is imported unconditionally from typing_extensions in all three
modules that use it, typing-extensions>=4.12.0 is a direct dependency and requires-python is
>=3.11. Two details worth naming: the dropped record's premise was accurate (create_publisher
and create_subscriber really are single-caller pass-throughs), and datetime.UTC, the constant
0004 credited with fixing 3.11 as the floor, is still imported in response.py.

Gates

Gate Result
pytest -q tests/test_adr_citations.py 7 passed
pytest -q (no-Redis suites: test_unit, test_fake, test_store_seam, test_tuning_defaults, test_adr_citations) 108 passed
ruff format --check 56 files already formatted
ruff check --no-fix All checks passed
eof-fixer . --check clean
lychee --offline over the three ADRs, docs/agents/domain.md, CONTEXT.md, AGENTS.md 3 links, 2 OK, 0 errors, 1 excluded

The integration suites (test_at_least_once, test_cancel, test_concurrency, test_delivery,
test_envelope, test_inspection, test_isolation, test_publish_api) need a live Redis and were
not run locally; CI covers them. No Python was touched, so the ruff and eof-fixer runs are
repo-wide rather than scoped to the change.

Rewrite each surviving record as a single paragraph, dropping the
**Decision:** line, the ## Context / ## Decision & rationale headings and
the **Revisit trigger:** section.

Dropped: 0002-keep-construction-factories - keeping two single-caller
constructor-bundling factories is trivially reversible and was not a real
trade-off, so it fails the admission test. Its rule, that the package mirrors
FastStream's own Redis broker layout, is folded into the new 0002.

Renumbered: 0003-no-per-call-middlewares-kwarg -> 0002,
0004-typing-extensions-over-version-gated-imports -> 0003.

No merges.
@lesnik512
lesnik512 merged commit c403622 into main Sep 19, 2026
8 checks passed
@lesnik512
lesnik512 deleted the docs/compress-adrs branch September 19, 2026 11:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant