Skip to content

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

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 3 records (961 words) to 3 (473 words), one paragraph each, in the shape ADR-FORMAT.md asks for. No record was dropped or merged, so the numbering and the slugs are unchanged and no citation had to move. 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 Reason
0001 no connection ContextProvider kept 0001 The boundary a sibling integration's reader will question; the provider would be public surface, so adding one later is a one-way door. Marginal on "hard to reverse" and the closest call of the three.
0002 no auto-inject sweep kept 0002 Deliberate deviation from the obvious setup_di convenience, with a concrete rejected alternative that is still tempting.
0003 per-job child teardown is reference-counted kept 0003 Reverting to the ownership boolean reintroduces a silent use-after-teardown; tests/test_jobs.py cites the record for exactly that.

Per record: 296 to 149 words, 272 to 155, 393 to 169. Removed from all three: the **Decision:** restatement of the title, the **Revisit trigger:** heading. 0001's and 0003's triggers are the real boundary of those decisions and survive as a clause in the paragraph; 0002's did not and was cut.

Citations

None moved. tests/test_jobs.py:238 still cites docs/adr/0003-per-job-child-teardown-is-reference-counted.md and docs/agents/domain.md still cites ADR-0001 and lists the first two filenames in its file-structure block; all resolve unchanged. The repo-wide sweep finds no reference to a number or a path that no longer exists.

Stale claims corrected

Checked against arq 0.28.0 in the lockfile and against modern_di_arq/main.py.

  • 0002 described an arq.func(...) entry as carrying "its own name/timeout/retry configuration". arq.worker.Function is a six-field record: name, coroutine, timeout_s, keep_result_s, keep_result_forever, max_tries. Result retention was missing from the list, and it is part of what a sweep would have to rebuild. Now "name, timeout, result retention and retry settings" and "any of its six fields".
  • 0002 said a sweep would have to handle an import string "without importing anything, since arq's own resolution of it is what decides which module is loaded and when". arq.func calls import_string eagerly and Worker.__init__ maps func over functions, so resolution happens at worker construction, not at job time. The conclusion holds; the wording now says what actually happens.
  • 0001 claimed modern-di-celery and modern-di-typer "decline for the same reason". That is a claim about two other repositories and cannot be verified from this one, so it was dropped rather than carried forward.
  • Verified and kept as written: 0001's ctx composition ({**self.ctx, **job_ctx} with job_id, job_try, enqueue_time, score, plus redis seeded by the worker) and the function.coroutine(ctx, *args, **kwargs) call site; 0003's depth key, its 1 to 0 close, the await-free transitions, and test_concurrent_inject_fanout_shares_one_child.

Gates

pytest -q tests/test_adr_citations.py (7 passed), the full suite (29 passed, nothing skipped: Redis was reachable, so the burst-worker tests ran), ruff format --check, ruff check --no-fix, eof-fixer . --check, and lychee --offline over the three records plus CONTEXT.md and AGENTS.md (0 errors). No Python was touched; the two ruff gates ran over the tree anyway.

All three records pass the admission test, so none were dropped or merged
and the numbering is unchanged. Each is now a single paragraph: 961 words
to 473. Two stale claims in 0002 were corrected against arq 0.28.0, and an
unverifiable claim about the celery and typer integrations was removed
from 0001.
@lesnik512
lesnik512 merged commit 2f047b2 into main Sep 19, 2026
7 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