Skip to content

docs(adr): compress to 2 records in the domain-modeling format - #50

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 2 records (589 words) to 2 (332 words), one paragraph each, in the shape
/domain-modeling's ADR format asks for. No record was dropped and none was merged, so the numbering,
the slugs and both citations are unchanged. Same treatment as modern-python/compose2pod#102.

Evaluation

Each record was tested against the admission test: hard to reverse, surprising without context, the
result of a real trade-off.

Old Outcome New Why
0001 retry default stays env-configured kept 0001 DB_RETRY_RETRIES_NUMBER is the library's whole configuration surface and the per-call re-read is a contract deployments depend on, so it is hard to reverse, and a one-function settings module is exactly the thing a reader would "fix".
0002 retriable taxonomy is asyncpg classes kept 0002 The tuple reads as a bare list of names with no codes near it, the SQLSTATE-table proposal recurs, and widening the taxonomy wrongly makes a retry replay a write.

What changed in each is the form, not the ruling: the **Decision:** lead, the review narrative and
the **Revisit trigger:** section are gone. Each revisit trigger survives as the paragraph's closing
clause, because in both cases it is the real boundary of the decision (a second source for the retry
default; a second axis asyncpg's class hierarchy does not encode).

Citations

No citation moved. tests/test_retry.py cites docs/adr/0001-retry-default-stays-env-configured.md
from the INVARIANT: docstring on test_the_default_attempt_count_is_re_read_on_every_call, and
docs/agents/domain.md names ADR-0001 in its conflict-flagging example and lists both filenames in
its tree sketch. All three still resolve. The repo-wide sweep finds no reference to a number that no
longer exists.

Stale claims

None. Every concrete claim was re-checked against the code and all of them hold: settings.py is
still one line with one caller, the default is still read inside wrapped_method on every call and
still defaults to 3, RETRIABLE_ASYNCPG_ERRORS is still a flat tuple behind a single isinstance,
and asyncpg 0.31.0 still carries 40001 / 08000 / 08003 / 40003 on the classes the records
name, with ConnectionDoesNotExistError still a subclass of PostgresConnectionError. Two claims
were made more precise rather than corrected: the isinstance is named as the one in
_is_retriable_link (is_retriable itself walks the __cause__ / __context__ chain around it),
and the executed rationale is pointed at tests/test_retriable.py by path.

Gates

  • pytest -q tests/test_adr_citations.py: 7 passed.
  • Full suite, pytest -q against a throwaway PostgreSQL container pointed at by DB_DSN: 40 passed.
    Nothing was skipped; without DB_DSN the connection, retry and transaction tests error out, which
    is why the container was started.
  • ruff format --check (24 files already formatted), ruff check --no-fix (clean), eof-fixer . --check (clean). No Python was touched.
  • lychee --offline --no-progress over both records plus CONTEXT.md and AGENTS.md: 2 links, 2 OK,
    0 errors.

Both records pass the admission test, so nothing was dropped and nothing
was merged; each is rewritten from the sectioned form into one paragraph.
The revisit triggers survive as the closing clause of each paragraph,
where they are the real boundary of the decision. Numbering, slugs and
the two citations are unchanged.
@lesnik512
lesnik512 merged commit 567eb1d into main Sep 19, 2026
7 checks passed
@lesnik512
lesnik512 deleted the docs/compress-adrs branch September 19, 2026 11:28
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