Initial extracted documentation set
This commit is contained in:
Rodin
+151
@@ -0,0 +1,151 @@
|
||||
# FastAPI Conventions Process
|
||||
|
||||
This file documents the workflow used to build and refine this repo so the extraction can be repeated without guesswork.
|
||||
|
||||
## Goal
|
||||
|
||||
Turn repeated FastAPI-adjacent service patterns from mature upstream codebases into concise convention docs with verifiable citations.
|
||||
|
||||
## Scope split
|
||||
|
||||
Keep this repo at the **framework/service-boundary** level.
|
||||
|
||||
Good fits:
|
||||
- route shape and handler thinness
|
||||
- dependency injection and request-scoped wiring
|
||||
- request/response schema boundaries
|
||||
- persistence/session handling in web services
|
||||
- app lifespan and startup/shutdown wiring
|
||||
- service testing at the HTTP/ASGI boundary
|
||||
|
||||
Do **not** re-document generic Python guidance here unless FastAPI meaningfully bends it.
|
||||
|
||||
## Upstream selection rule
|
||||
|
||||
Use a mixed source set: framework internals plus at least one or two app-style repos.
|
||||
|
||||
Current first-wave set:
|
||||
- `fastapi/fastapi`
|
||||
- `encode/starlette`
|
||||
- `pydantic/pydantic`
|
||||
- `encode/httpx`
|
||||
|
||||
Current refinement/app-layer set:
|
||||
- `fastapi-users/fastapi-users`
|
||||
- `fastapi/full-stack-fastapi-template`
|
||||
|
||||
Selection criteria:
|
||||
- respected and maintained
|
||||
- reveals real service-boundary behavior, not just toy usage
|
||||
- enough tests/examples to show lifecycle and caveats
|
||||
- includes both intended abstractions and pragmatic app wiring
|
||||
|
||||
## Directory contract
|
||||
|
||||
- `sources/` = raw evidence notes, one file per upstream repo
|
||||
- `patterns/` = synthesized conventions from repeated evidence
|
||||
- `comparison/` = explicit notes on where FastAPI conventions differ from broader Python patterns
|
||||
|
||||
## Step-by-step workflow
|
||||
|
||||
### 1) Separate framework conventions from Python-wide rules
|
||||
That split keeps guidance crisp and prevents vague “it depends” docs.
|
||||
|
||||
### 2) Make upstream code available locally
|
||||
Local checkouts make `file:line` verification cheap and keep the process grounded.
|
||||
|
||||
### 3) Write source notes first
|
||||
For each upstream repo, create `sources/<repo>.md` with:
|
||||
- why the repo was chosen
|
||||
- repeated patterns
|
||||
- caveats/counterexamples
|
||||
- exact `file:line` citations
|
||||
- pattern candidates supported by the evidence
|
||||
|
||||
Good source notes are dense evidence, not polished guidance.
|
||||
|
||||
### 4) Synthesize conventions from the strongest repeated signals
|
||||
Start with the topics where evidence is strongest.
|
||||
|
||||
In this repo that meant:
|
||||
- routes
|
||||
- dependencies
|
||||
- errors
|
||||
- testing
|
||||
- pydantic boundaries
|
||||
- persistence
|
||||
|
||||
Each convention doc should usually include:
|
||||
- the convention
|
||||
- why it exists
|
||||
- where to apply it
|
||||
- where not to cargo-cult it
|
||||
- preferred shapes
|
||||
- counterexamples
|
||||
- source signals/citations
|
||||
|
||||
### 5) Add comparison notes where FastAPI bends general Python guidance
|
||||
Examples:
|
||||
- dependency injection via callables/signatures instead of constructor wiring
|
||||
- request/response model boundaries as framework-facing objects
|
||||
- lifespan hooks instead of generic entrypoint/context patterns
|
||||
|
||||
### 6) Refine before broadening
|
||||
After the first useful convention set exists, do not rush to add more repos.
|
||||
|
||||
Instead:
|
||||
- improve convention docs in fresh contexts
|
||||
- strengthen citations
|
||||
- rewrite `sources/*.md` so they are denser and more reusable
|
||||
- reduce duplicated guidance across docs
|
||||
- preserve subtle framework caveats that are easy to flatten away
|
||||
|
||||
That was the right next move for this repo once the first source base existed.
|
||||
|
||||
## Fresh-context refinement pattern
|
||||
|
||||
A good refinement split is:
|
||||
- one fresh pass over convention docs
|
||||
- one fresh pass over source-note files
|
||||
- one fresh pass doing citation audit across both
|
||||
|
||||
## Review checklist
|
||||
|
||||
### For source notes
|
||||
- Does the file distinguish repeated conventions from isolated examples?
|
||||
- Does it preserve framework caveats and edge cases?
|
||||
- Are citations exact and fast to verify?
|
||||
- Does it avoid vague claims that are not source-backed?
|
||||
|
||||
### For convention docs
|
||||
- Is the guidance really FastAPI/service-boundary specific?
|
||||
- Is the framework-owned behavior described at the right seam?
|
||||
- Are testing and dependency recommendations grounded in actual code/tests?
|
||||
- Are exceptions and tradeoffs preserved instead of erased?
|
||||
|
||||
## Local git workflow used here
|
||||
|
||||
When the repo is ready for human review:
|
||||
1. initialize a local git repo
|
||||
2. stage the current documentation set
|
||||
3. create a single initial commit so review has a stable baseline
|
||||
|
||||
This repo intentionally avoids pushing or creating remotes unless explicitly requested.
|
||||
|
||||
## How to repeat this process next time
|
||||
|
||||
1. Define the scope split first.
|
||||
2. Pick a compact but high-signal upstream set.
|
||||
3. Build `sources/` before `patterns/`.
|
||||
4. Synthesize the strongest conventions first.
|
||||
5. Add comparison notes where the framework bends Python defaults.
|
||||
6. Run a fresh-context refinement wave.
|
||||
7. Initialize git only when the repo is reviewable.
|
||||
|
||||
## What to avoid
|
||||
|
||||
- documenting FastAPI from memory or tutorial vibes
|
||||
- mixing Python-wide guidance into this repo
|
||||
- broadening source coverage before tightening evidence quality
|
||||
- flattening dependency/lifespan/testing caveats into one-size-fits-all rules
|
||||
- weak citations that are annoying to re-check
|
||||
Reference in New Issue
Block a user