From 6eed5d8222802532cc1e18ab01a1ba585cc061c5 Mon Sep 17 00:00:00 2001 From: Artur Shiriev Date: Sun, 30 Aug 2026 20:41:32 +0300 Subject: [PATCH] docs: retire ROADMAP.md, migrating its open items to the tracker MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `ROADMAP.md` was the third state the workflow says does not exist: what outlives a PR is an open issue or an ADR, and a hand-maintained roadmap restates one of the two. #440 already cut its stale figures and its duplication of #434 — this removes the file that keeps re-earning that cleanup. Nothing is dropped without a home: - `## Guiding principles` and `## Explicitly not planned` were already stated, in more detail, by `docs/introduction/design-decisions.md` (sync-only resolution, conservative feature set, type safety, the separate-repo integration model) and `docs/introduction/comparison.md` (one wiring across every entrypoint). - The five open `## Under consideration` entries become issues #441–#445, each carrying its reasoning and a revisit trigger. - The Click refusal was a decision, not open work, so it becomes `docs/adr/0027-no-click-integration.md`. - The warm-singleton entry is #434 and needed no migration. Two entries are deliberately not migrated. "Dependency-graph export (Mermaid / Graphviz)" contradicted the standing **Graph rendering / visualization tooling** non-goal in `design-decisions.md`; filing it as open work would have re-opened a settled refusal. "More recipes; comparison and migration guides" is perpetual docs maintenance, not a tracked unit of work. `planning/releases/2.19.2.md` still names the roadmap as something that release shipped. That is a frozen record of what was true then and is left alone. Closes #438 Claude-Session: https://claude.ai/code/session_01FBic7HFGR6sdRfSW3cGEv2 --- ROADMAP.md | 69 --------------------------- docs/adr/0027-no-click-integration.md | 24 ++++++++++ 2 files changed, 24 insertions(+), 69 deletions(-) delete mode 100644 ROADMAP.md create mode 100644 docs/adr/0027-no-click-integration.md diff --git a/ROADMAP.md b/ROADMAP.md deleted file mode 100644 index 63de6af..0000000 --- a/ROADMAP.md +++ /dev/null @@ -1,69 +0,0 @@ -# Roadmap - -This roadmap is **exploratory** — a signal of direction and an invitation for -feedback, not a commitment to features or dates. If you have an opinion on any -item, or want to build one, please open or comment in -[Ideas Discussions](https://github.com/modern-python/modern-di/discussions). - -## Guiding principles - -- **Small, fully-typed, zero-dependency core.** -- **Sync resolution by design** — async work belongs in the framework lifespan, - not in dependency resolution. -- **One typed wiring across every entrypoint** — FastAPI, Litestar, FastStream, - Typer, plus workers and CLIs. -- **Official, uniformly-maintained integrations** over breadth at any cost. - -## Under consideration - -### More official integrations — "one wiring, every entrypoint" -Each new entrypoint lets your existing container cover more of your stack. -Already shipped: aiogram, aiohttp, arq, Celery, FastAPI, FastStream, Flask, -gRPC, Litestar, Starlette, taskiq, Typer (plus the `modern-di-pytest` plugin). -aiogram-dialog getters and callbacks are supported via the -`modern_di_aiogram.dialog` submodule. The gap below is drawn from Dishka's -integration set and sorted by community demand — exploratory, not a queue. - -**Lower / niche demand:** -- **Sanic** — async web is already covered by FastAPI/Litestar/Starlette. -- **pyTelegramBotAPI** (`telebot`) — older sync Telegram library. - -*Not planned:* **Click** — Typer already covers the CLI entrypoint and is -built on Click, so a separate adapter would be redundant. - -*Community-maintained if contributed* (as Dishka treats them): Pyramid, -Strawberry, Quart, RQ, APScheduler, Jobify, Flet, ag2. - -### Developer experience -- **Deeper pytest plugin** — parametrized overrides, autouse scope helpers, - async-fixture ergonomics. (modern-di already ships a first-party pytest - plugin; this makes it richer.) -- **First-class config providers** — pydantic-settings / environment / TOML. -- **Smoother abstract / `Protocol` → implementation binding** with clearer - scope- and cycle-violation diagnostics. -- **Dependency-graph export** (Mermaid / Graphviz) for debugging and docs. - -### Trust & observability -- **Optional OpenTelemetry instrumentation** of resolution and finalization. -- **Warm-singleton resolve headroom (C2)** — the scenario where modern-di trails - the slot-memoized frameworks on by-reference resolution. One direction remains - open and is gated on a reported bottleneck: - [issue #434](https://github.com/modern-python/modern-di/issues/434). For where - the cell actually stands, read - [Performance](https://modern-di.modern-python.org/introduction/performance/), - the only place these figures live. - -### Docs & ecosystem -- More recipes; comparison and migration guides. - -## Explicitly not planned - -- **Async resolution** (`await container.resolve(...)`, `AsyncFactory`) — this is - a deliberate design choice. Async setup/teardown happens in the framework - lifespan; resolution stays synchronous. - -## Feedback & contributions - -Items here are open for discussion and contribution. Comment in -[Ideas Discussions](https://github.com/modern-python/modern-di/discussions) to -shape priorities or volunteer to build one. diff --git a/docs/adr/0027-no-click-integration.md b/docs/adr/0027-no-click-integration.md new file mode 100644 index 0000000..a9c4051 --- /dev/null +++ b/docs/adr/0027-no-click-integration.md @@ -0,0 +1,24 @@ +# No Click integration — Typer already covers the CLI entrypoint + +**Decision:** no `modern-di-click` adapter. The CLI entrypoint is covered by `modern-di-typer`, and +a second adapter for the same layer would be redundant rather than additive. + +Typer is built on Click: a Typer application *is* a Click application, and `modern-di-typer` already +covers the CLI wiring seam — `setup_di` attaches the app-scoped container, `@inject` opens a +`REQUEST` child per command invocation and resolves `FromDI` parameters from it, while the root's +open/close stays the caller's `with container:` by the ruling in +[ADR-0020](0020-d3-root-lifecycle-inherent.md). A separate Click adapter would re-derive that same +contract against the lower-level API for no entrypoint that is not already reachable, while adding a +repository, a release cadence, and a compatibility matrix to maintain. That cost is the one the +[separate-repo integration model](../introduction/design-decisions.md) exists to keep proportionate +to the coverage bought. + +- **Vendoring Click support inside `modern-di-typer`** would let a plain Click app reuse the adapter, + but it makes that package's public surface depend on which of the two APIs the user built against, + and Typer's own Click version is an implementation detail it is free to move. +- **A community-maintained adapter** stays available: nothing here forbids one existing outside the + `modern-python` org, on the same footing as the other frameworks nobody has volunteered for. + +**Revisit trigger:** a Click-only application that `modern-di-typer` provably cannot wire — a +`click.Group` composed at runtime, or a Click-native plugin system Typer does not expose — reported +by someone hitting it, not hypothesized.