From 736a32aa147f4a8520af0edd709c7e7669f60ab6 Mon Sep 17 00:00:00 2001 From: iam-truongtrungnghia Date: Mon, 14 Sep 2026 09:51:10 +0700 Subject: [PATCH] docs: teach the tour and the runbooks about flask --- docs/runbook/add-an-adapter.md | 14 ++++++++++++-- docs/runbook/bump-a-toolchain-version.md | 5 +++++ docs/tour/01-toolchain.md | 4 ++++ docs/tour/08-adapters.md | 5 ++++- 4 files changed, 25 insertions(+), 3 deletions(-) diff --git a/docs/runbook/add-an-adapter.md b/docs/runbook/add-an-adapter.md index ae6bdfe..89b191a 100644 --- a/docs/runbook/add-an-adapter.md +++ b/docs/runbook/add-an-adapter.md @@ -17,6 +17,8 @@ ADAPTER_ROLE="api" # web, api, or app ADAPTER_TIER="B" ADAPTER_LANGUAGE="go" # "typescript" opts into packages/types ADAPTER_GENERATOR='' + # no generator? the package manager's project + # init: adapters/flask uses `uv init --bare` # ADAPTER_POST_GENERATE='' ``` @@ -26,11 +28,19 @@ generator itself gets wrong: `adapters/nestjs/adapter.env` sets it to un-await `bootstrap()` and run prettier once. Only reach for it once you've hit a real generator bug — it's a patch, not a default step. +The exception is a stack whose generator writes only a manifest: there the +dependencies are ordinary setup rather than a fixup, and `adapters/flask` +uses this field to `uv add` them. Either way it ends in a `grep` that fails +loudly, so a generator that reports success while writing nothing becomes a +build failure rather than an `ImportError` at container start. + ## 3. Write `mise.toml` All nine contract tasks. Declare the language in a local `[tools]` block so -it never reaches the project root. `format`, `lint`, and `check` must not -write. +it never reaches the project root — or, where the language's own tooling +owns the pin, declare the tool and let it read that pin (`adapters/flask` +pins `uv` and leaves python to `.python-version`). `format`, `lint`, and +`check` must not write. ## 4. Write `Dockerfile`, `.env.example`, `lefthook.fragment.yml` diff --git a/docs/runbook/bump-a-toolchain-version.md b/docs/runbook/bump-a-toolchain-version.md index 7b271e9..79aee82 100644 --- a/docs/runbook/bump-a-toolchain-version.md +++ b/docs/runbook/bump-a-toolchain-version.md @@ -9,6 +9,11 @@ - One adapter's own language (`php`'s Composer, or the pinned Node used by `laravel-inertia`'s build step): that adapter's own `mise.toml`, e.g. `adapters/laravel-api/mise.toml`. +- `flask`'s python is the exception, and searching the `[tools]` blocks for + it finds nothing: `adapters/flask/mise.toml` pins `uv` only, and the + interpreter is pinned in `adapters/flask/.python-version`, the file uv + reads. Bumping it means editing that file and the `--python` argument in + `adapters/flask/adapter.env`, which sets `requires-python` at generation. ## 2. Edit the version diff --git a/docs/tour/01-toolchain.md b/docs/tour/01-toolchain.md index 17523f2..0a45af4 100644 --- a/docs/tour/01-toolchain.md +++ b/docs/tour/01-toolchain.md @@ -16,6 +16,10 @@ and, in a generated project, `common/mise.root.toml`'s (`node`, `pnpm`, any adapter. - `adapters/laravel-api/mise.toml` — a language declared in a local `[tools]` block so it never reaches the project root (see 08 — Adapters). +- `adapters/flask/mise.toml` — the same rule with the pin somewhere else + again: it declares `uv` and no python, because uv resolves its own managed + interpreter and would install a mise-pinned one only to ignore it. + `adapters/flask/.python-version` is the file uv actually reads. - Upstream for comparison: immich's own root `https://github.com/immich-app/immich/blob/351be95/mise.toml`, which pins every service's language in one place — the opposite of this project's diff --git a/docs/tour/08-adapters.md b/docs/tour/08-adapters.md index 2653e17..8d2ba3f 100644 --- a/docs/tour/08-adapters.md +++ b/docs/tour/08-adapters.md @@ -4,7 +4,10 @@ An adapter is an overlay, not a vendored application: `scaffold` invokes a framework's own generator (`create-next-app`, `nest new`, `composer -create-project`) and then copies its own files on top of the result. +create-project`) and then copies its own files on top of the result. Where a +framework ships no generator, the package manager's project init stands in — +`flask` runs `uv init --bare`, which writes a `pyproject.toml` and nothing +else, and the overlay supplies the application itself. `lib/lint.sh` requires four of them — `adapter.env`, `mise.toml`, `Dockerfile`, `.env.example` — and an adapter may ship more: `nextjs` adds `next.config.ts` and `.prettierignore`, `laravel-api` adds `phpstan.neon`