From ce1f4f00b5304abc91381f29e31f12b93c595c16 Mon Sep 17 00:00:00 2001 From: Artur Shiriev Date: Mon, 7 Sep 2026 08:36:23 +0300 Subject: [PATCH] chore: drop the asset-hotlinking ADR and trim AGENTS.md Removes docs/adr/0003-docs-vendor-assets-readmes-hotlink.md, renumbers the flask-horn ADR into the gap, and fixes the three references. Also drops the AGENTS.md paragraph describing what is enforced only at review time. --- AGENTS.md | 9 ++------ brand/README.md | 3 +-- brand/build/symbols.py | 2 +- ...0003-docs-vendor-assets-readmes-hotlink.md | 22 ------------------- ...03-flask-horn-historical-artwork-grant.md} | 0 5 files changed, 4 insertions(+), 32 deletions(-) delete mode 100644 docs/adr/0003-docs-vendor-assets-readmes-hotlink.md rename docs/adr/{0004-flask-horn-historical-artwork-grant.md => 0003-flask-horn-historical-artwork-grant.md} (100%) diff --git a/AGENTS.md b/AGENTS.md index c5e0159..b7ac0dc 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -50,9 +50,7 @@ meanwhile. That lag is self-healing — note it, never block the listing on it. ## Brand surfaces -A repo's brand assets are generated here, in `brand/projects//`. Which of them a -repo hotlinks and which it vendors is settled in -[`docs/adr/0003-docs-vendor-assets-readmes-hotlink.md`](docs/adr/0003-docs-vendor-assets-readmes-hotlink.md). +A repo's brand assets are generated here, in `brand/projects//`. A docs site's `docs/index.md` replaces its `# ` heading with a `.mp-hero` block holding both lockup variants. Add no `title:` front matter there: Material titles the @@ -102,10 +100,7 @@ comment, or `mkdocs.yml` costs every turn and rots in two places at once. An invariant is a test whose name is the claim, with a docstring opening `INVARIANT:` and a second paragraph naming **what breaks it** — design rationale, not a report of -what this one test catches. Nothing enforces that shape, and nothing checks that an ADR -path cited from code or from this file still resolves; both are read at review time. -Both ADRs and `INVARIANT:` docstrings ratchet: nothing prunes a record once its call is -settled. Keeping them lean is a standing habit. +what this one test catches. ## Agent skills diff --git a/brand/README.md b/brand/README.md index 408a1e0..663809f 100644 --- a/brand/README.md +++ b/brand/README.md @@ -63,8 +63,7 @@ Repos with a docs site also get a `social-card.svg` + `social-card.png` (1280×640 og:image): the repo mark on a green panel beside its name, tagline, and docs URL on cream. The docs-site repos are listed in `brand/build/projects.py::DOCS_REPOS`. These repos also use the lockup as a -centered hero on their `docs/index.md`, vendored into the repo's `docs/assets/` -(see `docs/adr/0003-docs-vendor-assets-readmes-hotlink.md`). +centered hero on their `docs/index.md`, vendored into the repo's `docs/assets/`. PNGs are palette-quantized at build time (`brand/build/raster.py`, Pillow FASTOCTREE) — indexed-colour, with no visible change (the art is flat-colour). diff --git a/brand/build/symbols.py b/brand/build/symbols.py index 12beeb1..9225b60 100644 --- a/brand/build/symbols.py +++ b/brand/build/symbols.py @@ -532,7 +532,7 @@ def flask_horn(cx: float, cy: float, r: float) -> str: recoloured gold. The bands are negative space in the source artwork. Uses Flask's literal logo path under a grant Pallets has since withdrawn; see - docs/adr/0004-flask-horn-historical-artwork-grant.md.""" + docs/adr/0003-flask-horn-historical-artwork-grant.md.""" sc = (2.04 * r) / 500.0 body = "".join(f'<path d="{d}" fill="{GOLD}"/>' for d in FLASK_PATHS) return ( diff --git a/docs/adr/0003-docs-vendor-assets-readmes-hotlink.md b/docs/adr/0003-docs-vendor-assets-readmes-hotlink.md deleted file mode 100644 index ee76bae..0000000 --- a/docs/adr/0003-docs-vendor-assets-readmes-hotlink.md +++ /dev/null @@ -1,22 +0,0 @@ -# Docs sites vendor brand assets; READMEs hotlink them - -**Decision:** A repo's `README.md` embeds its lockup by absolute -`raw.githubusercontent.com/modern-python/.github/main/brand/projects/<repo>/` URL, so no asset file -is committed to that repo. A repo's **docs site** does the opposite: it copies `lockup-light.svg` -and `lockup-dark.svg` into its own `docs/assets/`. - -Hotlinking everywhere was the tidier option — one copy of every asset, in the repo that generates -them, and a regenerated mark propagates without touching 26 repos. It is right for READMEs, which -GitHub renders directly and which have no build step to break. - -It is wrong for docs sites. `mkdocs build --strict` does not check external URLs, so a moved or -renamed asset fails silently at serve time instead of at build time; the build also becomes subject -to CDN caching lag, to a site's CSP, and to network access, which breaks offline builds. Docs sites -already vendor every other brand asset (`mark.svg`, `favicon.svg`, `social-card.png` are committed -copies today), so vendoring the lockup is the consistent choice as well as the robust one. - -The cost is accepted and real: a lockup change means re-copying into each docs repo. That is the -same manual step those repos already take for their other assets. - -**Revisit trigger:** MkDocs gains external-link validation under `--strict`, or the number of docs -repos makes the re-copy step the thing that actually breaks. diff --git a/docs/adr/0004-flask-horn-historical-artwork-grant.md b/docs/adr/0003-flask-horn-historical-artwork-grant.md similarity index 100% rename from docs/adr/0004-flask-horn-historical-artwork-grant.md rename to docs/adr/0003-flask-horn-historical-artwork-grant.md