diff --git a/architecture/org-profile.md b/architecture/org-profile.md index e8e85c4..af2f1c4 100644 --- a/architecture/org-profile.md +++ b/architecture/org-profile.md @@ -13,19 +13,24 @@ frontmatter; dated by git. live) and a static `coverage 100%` badge. The coverage claim holds org-wide because every repo's CI enforces a 100%-coverage guard; it renders unlinked (there is no org-level coverage URL). -4. **Four category tables** — `Project | What it is | Badges`, in order: - **Project templates**, **Dependency injection**, **Microservices, HTTP & messaging**, - **Utilities**. The `What it is` column carries the canonical ≤120-char one-liner - (one of the three metadata surfaces kept consistent across GitHub - description, pyproject `description`, and this blurb). +4. **Four category tables**, in order: **Project templates**, **Dependency + injection**, **Microservices, HTTP & messaging**, **Utilities**. The + `What it is` column carries the canonical ≤120-char one-liner (one of the + three metadata surfaces kept consistent across GitHub description, + pyproject `description`, and this blurb). The three published-library + tables (DI, microservices, utilities) share the shape + `Project | What it is | Stars | Downloads`; the templates table is + `Project | What it is | Stars | Badges`. ## Badge rules -- **Published libraries** get a four-badge strip: GitHub stars → stargazers, - PyPI version, monthly downloads (`static.pepy.tech/badge//month`), and a - Context7 docs badge → `context7.com/modern-python/`. -- **Templates** (`*-sqlalchemy-template`, not on PyPI) get stars + Context7 + a - static `type: template` chip — no version/downloads columns, so no empty cells. +- **Published libraries** get a Stars shield → stargazers, and a monthly + Downloads shield (`static.pepy.tech/badge//month`) → the pepy project + page. +- **Templates** (`*-sqlalchemy-template`, not on PyPI) get a Stars shield and, + in their Badges cell, only a static `type: template` chip — templates have + no Downloads column, hence that column keeps the generic "Badges" header + instead of "Downloads". - All badges use flat (default) style so row heights align. Downloads use the pepy baked SVG, not the flaky shields `pypi/dm` endpoint. Every number is a live shield (no hand-typed stats that could go stale). diff --git a/docs/index.md b/docs/index.md index c4e2a6c..a2b9af4 100644 --- a/docs/index.md +++ b/docs/index.md @@ -66,8 +66,9 @@ production Python services. Use one piece or all of them — each is independent SQLAlchemy 2, PostgreSQL, with dependency injection already wired. - **Wire your dependencies** with [`modern-di`](https://github.com/modern-python/modern-di) — typed, scoped - dependency injection with one wiring shared across FastAPI, Litestar, - Starlette, aiohttp, FastStream, and Typer. + dependency injection with one wiring shared across web frameworks (FastAPI, + Litestar, Starlette, Flask, aiohttp), task queues (Celery, arq, taskiq), RPC + and messaging (gRPC, FastStream, aiogram), and CLIs (Typer). ([`that-depends`](https://github.com/modern-python/that-depends), its production-proven predecessor, is still maintained.) - **Call other services reliably** with @@ -96,12 +97,18 @@ catalog below. ## Dependency injection { #di } - [`modern-di`](https://github.com/modern-python/modern-di) — powerful DI framework with scopes. +- [`modern-di-aiogram`](https://github.com/modern-python/modern-di-aiogram) — `modern-di` integration for aiogram. - [`modern-di-aiohttp`](https://github.com/modern-python/modern-di-aiohttp) — `modern-di` integration for aiohttp. +- [`modern-di-arq`](https://github.com/modern-python/modern-di-arq) — `modern-di` integration for arq. +- [`modern-di-celery`](https://github.com/modern-python/modern-di-celery) — `modern-di` integration for Celery. - [`modern-di-fastapi`](https://github.com/modern-python/modern-di-fastapi) — `modern-di` integration for FastAPI. - [`modern-di-faststream`](https://github.com/modern-python/modern-di-faststream) — `modern-di` integration for FastStream. +- [`modern-di-flask`](https://github.com/modern-python/modern-di-flask) — `modern-di` integration for Flask. +- [`modern-di-grpc`](https://github.com/modern-python/modern-di-grpc) — `modern-di` integration for gRPC. - [`modern-di-litestar`](https://github.com/modern-python/modern-di-litestar) — `modern-di` integration for Litestar. - [`modern-di-pytest`](https://github.com/modern-python/modern-di-pytest) — `modern-di` integration for pytest. - [`modern-di-starlette`](https://github.com/modern-python/modern-di-starlette) — `modern-di` integration for Starlette. +- [`modern-di-taskiq`](https://github.com/modern-python/modern-di-taskiq) — `modern-di` integration for taskiq. - [`modern-di-typer`](https://github.com/modern-python/modern-di-typer) — `modern-di` integration for Typer. - [`that-depends`](https://github.com/modern-python/that-depends) — predecessor DI framework, still actively maintained. @@ -115,6 +122,7 @@ catalog below. ## Utilities { #utilities } +- [`compose2pod`](https://github.com/modern-python/compose2pod) — convert a Docker Compose file into a script that runs its services as a single Podman pod. - [`db-retry`](https://github.com/modern-python/db-retry) — retry helpers for database operations. - [`eof-fixer`](https://github.com/modern-python/eof-fixer) — automatically fix newlines at the end of files. - [`semvertag`](https://github.com/modern-python/semvertag) — auto-tag your GitHub/GitLab repo with semantic version tags from CI. diff --git a/planning/changes/2026-07-13.01-seven-repos-surfaces.md b/planning/changes/2026-07-13.01-seven-repos-surfaces.md new file mode 100644 index 0000000..5fd4211 --- /dev/null +++ b/planning/changes/2026-07-13.01-seven-repos-surfaces.md @@ -0,0 +1,165 @@ +--- +summary: Put the seven newly-branded repos on their public surfaces — README lockup banners in each repo, rows on the profile README and docs site, compose2pod's GitHub metadata — and correct the stale badge description in architecture/org-profile.md. +--- + +# Design: Surface the seven newly-branded repos + +## Summary + +The seven repos that just got brand marks +(`planning/changes/2026-07-12.01-seven-new-project-marks.md`) are still invisible +everywhere a reader would look for them. This change adds the README `` +banner to each of the seven repos, lists them on `profile/README.md` and +`docs/index.md`, brings `compose2pod`'s GitHub metadata in line with org +conventions, and fixes a stale claim in `architecture/org-profile.md`. + +Work spans two places: this repo (one PR) and the seven integration repos (one PR +each, banner-only). + +## Motivation + +The marks exist and are served from `main`, but nothing points at them: + +- None of the seven READMEs carries the lockup banner every sibling repo has — + they still open with a bare `# ` heading. +- None of the seven appears in `profile/README.md` (the org landing page) or + `docs/index.md` (the catalog on modern-python.org). A visitor cannot discover + them at all. +- `compose2pod` has **no website field and no topics** — the only one of the seven + out of line with the org's "three surfaces kept consistent" rule. (The six + `modern-di-*` repos already have description, website and topics set.) + +All seven are published on PyPI, so the Downloads badge resolves for each. + +Separately, `architecture/org-profile.md` is **wrong** about the surface this +change edits. It claims published libraries carry a four-badge strip (stars, PyPI +version, downloads, Context7). Change `2026-07-02.03-profile-badge-columns` +deliberately dropped the PyPI-version and Context7 badges and gave Stars its own +column, but only edited `profile/README.md` — the architecture doc was never +updated. Since `architecture/` is the living truth for this capability and this +change modifies exactly that capability, the correction rides here. + +## Design + +### 1. README banners — the seven repos (one PR each) + +Each repo's leading `# ` heading is replaced by the centred `` +block every sibling already uses, hotlinking the assets from this repo (no asset +files are committed to the integration repos): + +```html +

+ + + + <repo> + +

+``` + +`lockup.png` is the light lockup: it is the fallback PyPI renders (PyPI serves the +README on a white background and ignores ``), which is why the light +variant is the correct ``. + +Nothing else in those READMEs changes. + +### 2. Profile README — `profile/README.md` + +Six rows appended to the **Dependency injection** table, keeping it alphabetical +by repo (`aiogram` sorts before `aiohttp`, so it leads the integrations), and one +row appended to **Utilities** for `compose2pod`. Columns are the current +`Project | What it is | Stars | Downloads` — Stars and Downloads shields only, per +the badge set actually in use. + +The `What it is` blurb is the canonical one-liner, identical to the GitHub +description and pyproject `description`: + +| repo | blurb | +| --- | --- | +| `modern-di-aiogram` | modern-di integration for aiogram | +| `modern-di-arq` | modern-di integration for arq | +| `modern-di-celery` | modern-di integration for Celery | +| `modern-di-flask` | modern-di integration for Flask | +| `modern-di-grpc` | modern-di integration for gRPC | +| `modern-di-taskiq` | modern-di integration for taskiq | +| `compose2pod` | Convert a Docker Compose file into a script that runs its services as a single Podman pod | + +`compose2pod` goes in **Utilities** rather than a new section: `semvertag` is +already a CI/devops CLI rather than a library, so the section is not purely +library helpers, and two projects do not justify restructuring two published +surfaces. + +### 3. Docs site — `docs/index.md` + +Six bullets appended to the `Dependency injection { #di }` list and one to +`Utilities { #utilities }`, in the file's existing lowercase style +(`` `modern-di-aiogram` — `modern-di` integration for aiogram.``). + +**The "The stack" prose is rewritten by category.** It currently reads "one wiring +shared across FastAPI, Litestar, Starlette, aiohttp, FastStream, and Typer". +Extending that flat list to twelve names would be unreadable and would keep +growing. It becomes: + +> **Wire your dependencies** with `modern-di` — typed, scoped dependency injection +> with one wiring shared across web frameworks (FastAPI, Litestar, Starlette, +> Flask, aiohttp), task queues (Celery, arq, taskiq), RPC and messaging (gRPC, +> FastStream, aiogram), and CLIs (Typer). + +This also communicates something the flat list did not: that `modern-di` now +reaches well beyond web frameworks. + +### 4. GitHub metadata — `compose2pod` only + +Set via `gh`; the other six are already correct and are left alone. + +- **Website:** `https://modern-python.org` (it has no docs site of its own). +- **Topics:** `python, docker, podman, docker-compose, containers, cli` — drawn + from the shared org vocabulary (`python`, `docker`, `cli`) plus its own domain. +- **Description:** already canonical; unchanged. + +### 5. Architecture — `architecture/org-profile.md` + +Correct the **Badge rules** section to describe what the tables actually carry: +DI/services/utilities tables are `Project | What it is | Stars | Downloads` +(stars + monthly pepy downloads); the templates table is +`Project | What it is | Stars | Badges`, its Badges cell holding only the +`type: template` chip. Remove the claim that published libraries carry PyPI-version +and Context7 badges — they were dropped on 2026-07-02 and do not exist in the file. + +## Non-goals + +- **No new brand assets.** All seven marks and lockups already exist on `main`. +- **No docs sites** for any of the seven, and so no social cards — none ships an + `mkdocs.yml`, and none is in `DOCS_REPOS`. +- **No metadata changes to the six `modern-di-*` repos** — their description, + website and topics are already correct; touching them would be churn. +- **No restructuring** of the profile's four-category taxonomy. + +## Testing + +- `just check-planning` passes; `just test` stays green (this change touches no + `brand/` code, so the mark tests are unaffected). +- Every banner URL resolves: `curl -sI` each of the 21 asset URLs + (7 repos × `lockup-dark.svg`, `lockup-light.svg`, `lockup.png`) returns 200 from + `raw.githubusercontent.com/.../main/...`. These are hotlinks — a typo shows up as + a broken image, not a build failure, so this check is the guard. +- Each of the seven repo READMEs renders with the banner and no leftover `# + ` heading; the PyPI long-description still renders (the `` fallback is + the light PNG). +- `profile/README.md` and `docs/index.md`: every new row/bullet's links resolve, + and the blurb matches the repo's GitHub description character for character. +- `mkdocs build --strict` succeeds for the docs site. +- `gh repo view modern-python/compose2pod` shows the intended website and topics. + +## Risk + +- **Low: a banner hotlink 404s.** The assets are on `main` in this repo and were + verified after merge. Mitigated by the `curl` sweep above; a broken link is + cosmetic and trivially fixable, not a build break. +- **Low: blurb drifts from the GitHub description.** Both are copied from the same + canonical one-liner in this change, and the org convention keeps the three + surfaces (GitHub description, pyproject `description`, profile blurb) in sync. +- **Low: seven separate PRs land inconsistently.** They are mechanical and + identical in shape; each is reviewed against the same snippet. +- **Low: `compose2pod` reads oddly under "Utilities".** Accepted — see §2. It is + the least-bad fit until there are enough devops tools to justify a section. diff --git a/profile/README.md b/profile/README.md index 5ce1db7..6f592b2 100644 --- a/profile/README.md +++ b/profile/README.md @@ -24,12 +24,18 @@ Open-source templates and libraries for building production-ready Python applica | Project | What it is | Stars | Downloads | |---|---|---|---| | [`modern-di`](https://github.com/modern-python/modern-di) | Powerful DI framework with scopes | [![Stars](https://img.shields.io/github/stars/modern-python/modern-di)](https://github.com/modern-python/modern-di/stargazers) | [![Downloads](https://static.pepy.tech/badge/modern-di/month)](https://pepy.tech/projects/modern-di) | +| [`modern-di-aiogram`](https://github.com/modern-python/modern-di-aiogram) | modern-di integration for aiogram | [![Stars](https://img.shields.io/github/stars/modern-python/modern-di-aiogram)](https://github.com/modern-python/modern-di-aiogram/stargazers) | [![Downloads](https://static.pepy.tech/badge/modern-di-aiogram/month)](https://pepy.tech/projects/modern-di-aiogram) | | [`modern-di-aiohttp`](https://github.com/modern-python/modern-di-aiohttp) | modern-di integration for aiohttp | [![Stars](https://img.shields.io/github/stars/modern-python/modern-di-aiohttp)](https://github.com/modern-python/modern-di-aiohttp/stargazers) | [![Downloads](https://static.pepy.tech/badge/modern-di-aiohttp/month)](https://pepy.tech/projects/modern-di-aiohttp) | +| [`modern-di-arq`](https://github.com/modern-python/modern-di-arq) | modern-di integration for arq | [![Stars](https://img.shields.io/github/stars/modern-python/modern-di-arq)](https://github.com/modern-python/modern-di-arq/stargazers) | [![Downloads](https://static.pepy.tech/badge/modern-di-arq/month)](https://pepy.tech/projects/modern-di-arq) | +| [`modern-di-celery`](https://github.com/modern-python/modern-di-celery) | modern-di integration for Celery | [![Stars](https://img.shields.io/github/stars/modern-python/modern-di-celery)](https://github.com/modern-python/modern-di-celery/stargazers) | [![Downloads](https://static.pepy.tech/badge/modern-di-celery/month)](https://pepy.tech/projects/modern-di-celery) | | [`modern-di-fastapi`](https://github.com/modern-python/modern-di-fastapi) | modern-di integration for FastAPI | [![Stars](https://img.shields.io/github/stars/modern-python/modern-di-fastapi)](https://github.com/modern-python/modern-di-fastapi/stargazers) | [![Downloads](https://static.pepy.tech/badge/modern-di-fastapi/month)](https://pepy.tech/projects/modern-di-fastapi) | | [`modern-di-faststream`](https://github.com/modern-python/modern-di-faststream) | modern-di integration for FastStream | [![Stars](https://img.shields.io/github/stars/modern-python/modern-di-faststream)](https://github.com/modern-python/modern-di-faststream/stargazers) | [![Downloads](https://static.pepy.tech/badge/modern-di-faststream/month)](https://pepy.tech/projects/modern-di-faststream) | +| [`modern-di-flask`](https://github.com/modern-python/modern-di-flask) | modern-di integration for Flask | [![Stars](https://img.shields.io/github/stars/modern-python/modern-di-flask)](https://github.com/modern-python/modern-di-flask/stargazers) | [![Downloads](https://static.pepy.tech/badge/modern-di-flask/month)](https://pepy.tech/projects/modern-di-flask) | +| [`modern-di-grpc`](https://github.com/modern-python/modern-di-grpc) | modern-di integration for gRPC | [![Stars](https://img.shields.io/github/stars/modern-python/modern-di-grpc)](https://github.com/modern-python/modern-di-grpc/stargazers) | [![Downloads](https://static.pepy.tech/badge/modern-di-grpc/month)](https://pepy.tech/projects/modern-di-grpc) | | [`modern-di-litestar`](https://github.com/modern-python/modern-di-litestar) | modern-di integration for Litestar | [![Stars](https://img.shields.io/github/stars/modern-python/modern-di-litestar)](https://github.com/modern-python/modern-di-litestar/stargazers) | [![Downloads](https://static.pepy.tech/badge/modern-di-litestar/month)](https://pepy.tech/projects/modern-di-litestar) | | [`modern-di-pytest`](https://github.com/modern-python/modern-di-pytest) | modern-di integration for pytest | [![Stars](https://img.shields.io/github/stars/modern-python/modern-di-pytest)](https://github.com/modern-python/modern-di-pytest/stargazers) | [![Downloads](https://static.pepy.tech/badge/modern-di-pytest/month)](https://pepy.tech/projects/modern-di-pytest) | | [`modern-di-starlette`](https://github.com/modern-python/modern-di-starlette) | modern-di integration for Starlette | [![Stars](https://img.shields.io/github/stars/modern-python/modern-di-starlette)](https://github.com/modern-python/modern-di-starlette/stargazers) | [![Downloads](https://static.pepy.tech/badge/modern-di-starlette/month)](https://pepy.tech/projects/modern-di-starlette) | +| [`modern-di-taskiq`](https://github.com/modern-python/modern-di-taskiq) | modern-di integration for taskiq | [![Stars](https://img.shields.io/github/stars/modern-python/modern-di-taskiq)](https://github.com/modern-python/modern-di-taskiq/stargazers) | [![Downloads](https://static.pepy.tech/badge/modern-di-taskiq/month)](https://pepy.tech/projects/modern-di-taskiq) | | [`modern-di-typer`](https://github.com/modern-python/modern-di-typer) | modern-di integration for Typer | [![Stars](https://img.shields.io/github/stars/modern-python/modern-di-typer)](https://github.com/modern-python/modern-di-typer/stargazers) | [![Downloads](https://static.pepy.tech/badge/modern-di-typer/month)](https://pepy.tech/projects/modern-di-typer) | | [`that-depends`](https://github.com/modern-python/that-depends) | Predecessor DI framework, still actively maintained | [![Stars](https://img.shields.io/github/stars/modern-python/that-depends)](https://github.com/modern-python/that-depends/stargazers) | [![Downloads](https://static.pepy.tech/badge/that-depends/month)](https://pepy.tech/projects/that-depends) | @@ -47,6 +53,7 @@ Open-source templates and libraries for building production-ready Python applica | Project | What it is | Stars | Downloads | |---|---|---|---| +| [`compose2pod`](https://github.com/modern-python/compose2pod) | Convert a Docker Compose file into a script that runs its services as a single Podman pod | [![Stars](https://img.shields.io/github/stars/modern-python/compose2pod)](https://github.com/modern-python/compose2pod/stargazers) | [![Downloads](https://static.pepy.tech/badge/compose2pod/month)](https://pepy.tech/projects/compose2pod) | | [`db-retry`](https://github.com/modern-python/db-retry) | Retry helpers for PostgreSQL / SQLAlchemy database operations | [![Stars](https://img.shields.io/github/stars/modern-python/db-retry)](https://github.com/modern-python/db-retry/stargazers) | [![Downloads](https://static.pepy.tech/badge/db-retry/month)](https://pepy.tech/projects/db-retry) | | [`eof-fixer`](https://github.com/modern-python/eof-fixer) | Automatically fix newlines at the end of files | [![Stars](https://img.shields.io/github/stars/modern-python/eof-fixer)](https://github.com/modern-python/eof-fixer/stargazers) | [![Downloads](https://static.pepy.tech/badge/eof-fixer/month)](https://pepy.tech/projects/eof-fixer) | | [`semvertag`](https://github.com/modern-python/semvertag) | Auto-tag your GitHub/GitLab repo with semantic version tags from CI | [![Stars](https://img.shields.io/github/stars/modern-python/semvertag)](https://github.com/modern-python/semvertag/stargazers) | [![Downloads](https://static.pepy.tech/badge/semvertag/month)](https://pepy.tech/projects/semvertag) |