Skip to content

docs: fix drifted facts in the org profile, site, and contributor docs - #124

Merged
lesnik512 merged 1 commit into
mainfrom
docs/fix-facts
Oct 3, 2026
Merged

lesnik512 merged 1 commit into
mainfrom
docs/fix-facts

Conversation

@lesnik512

Copy link
Copy Markdown
Member

Summary

A review of the org repo found facts that drifted from their sources. Each was checked against the source before changing it.

Changes

  • Delete brand/STORY.md and brand/story-assets/. A grep of the whole repo (mkdocs.yml, tests, brand build scripts, READMEs) found no references outside STORY.md itself. brand/README.md did not link to it.
  • profile/README.md: the httpware row said "Python HTTP client framework with sync & async clients and built-in resilience". httpware/pyproject.toml says "Typed, resilient HTTP clients for Python, sync and async" (MD1). Every other profile row already matched its pyproject.
  • docs/index.md catalog: every row now uses its repo's pyproject description. Rows that had drifted: both templates (the litestar one was missing "with DI"), modern-di, all modern-di-* integrations (modern-di-pytest called itself a plain integration), that-depends, lite-bootstrap, httpware, faststream-redis-timers, faststream-concurrent-aiokafka, faststream-outbox, db-retry, eof-fixer, and semvertag. The list separator is now : instead of an em dash. The httpware row now uses the pyproject string, which supersedes the "add circuit breaker" fix. The stack section at docs/index.md:77 already lists retry, bulkhead, and circuit breaker.
  • Add chat-app, a public repo, to the Project templates table and the site catalog. It uses chat-app/pyproject.toml's description: "Reference chat application for the modern-python organisation". tests/test_profile.py requires every profile row to have a project mark, so it also gets a MANIFEST entry in brand/build/projects.py. Like the templates, it reuses the org chevron because it is not a published library. Its rendered assets are in brand/projects/chat-app/, and it is added to scripts/check_site_content.sh.
  • CONTRIBUTING.md: every sibling repo has a justfile, so the "where a justfile exists" clause is gone. The suggested check uv run ruff check . applies fixes because the canonical ruff config sets fix = true and unsafe-fixes = true, so the step now points to just lint-ci, which is read-only, and just lint, which fixes. The templates and chat-app have no lint-ci recipe, and the text says so. Of the sibling justfiles, only that-depends/justfile:11-12,17-18 runs mypy and pyrefly.
  • brand/README.md: the icon is a chevron between the two snakes (brand/build/geometry.py:6-17, _icon_mark draws a <polyline> chevron), so it no longer mentions a gold core dot. The header logo follow-up is done (mkdocs.yml:16 logo: assets/mark.svg, built by geometry.mark), so that section is removed.
  • Prose: the that-depends line on the home page now says "the older DI framework". The migration-guide sentence in the profile and on the home page is rewritten. The docs/standard.md opener is rewritten too.

Follow-ups, not changed here:

  • MD1: chat-app's GitHub description ("Reference chat application showing modern-python libraries composed on a realistic domain") differs from its pyproject description.
  • brand/build/projects.py::DOCS_REPOS social-card taglines are the old home page one-liners, for example httpware's "(retry, bulkhead)". Changing them means regenerating the social cards.

Checklist

  • Lint and format pass (ruff) (this repo has no lint recipe)
  • Type check passes (ty)
  • Tests pass and new behavior is covered (uv run pytest: 172 passed; uv run mkdocs build --strict clean; scripts/check_site_content.sh passes; lychee --offline reports 0 errors)
  • Build succeeds (uv build) if packaging or build config changed
  • Repo metadata stays consistent across the three surfaces (GitHub description, pyproject description, profile blurb) if this touches packaging (except the chat-app GitHub description noted above)

- Delete brand/STORY.md and brand/story-assets/ (nothing else referenced them)
- Use each repo's pyproject description for every row in profile/README.md
  and docs/index.md (httpware, templates, DI, services, utilities)
- Add chat-app to the profile, site catalog, project marks, and site link check
- CONTRIBUTING: point to just lint-ci / just lint, drop the "where a justfile
  exists" clause, say that-depends is the repo that runs mypy and pyrefly
- brand/README: describe the chevron icon, drop the done header-logo follow-up
- Reword the that-depends and migration-guide lines and the standard.md opener
@lesnik512
lesnik512 merged commit bb5563e into main Oct 3, 2026
3 checks passed
@lesnik512
lesnik512 deleted the docs/fix-facts branch October 3, 2026 13:59
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