fastapi-conventions/PROCESS.md

# 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.

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

## Handling mixed-concern source code

Upstream service code will often mix FastAPI behavior, Pydantic boundary behavior, and ordinary Python design in the same function or line.

When that happens:
- do not classify the whole snippet by file name or repo alone
- split the evidence into **framework-owned signal** and **generic Python signal**
- keep the request/response, dependency, lifecycle, and HTTP-boundary lesson here
- push reusable language-level guidance back to `python-patterns`

If the claim still makes full sense after removing FastAPI and HTTP, it is probably too generic to live here as a FastAPI convention.

## 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.

## 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