Make commands
Single page to discover what `make` can do in this project: daily workflows, release gates, and full command inventory from the `Makefile`.
Canonical workflows
| Workflow | Command | Purpose |
|---|---|---|
| Autofix loop | make fix |
Apply formatting, lint, and docs autofixes. |
| Local quality gate | make verify |
Run lint, typing, OpenAPI checks, contract tests, tests, and docs sync. |
| CI-equivalent gate | make verify-ci |
Run stricter non-mutating checks including docs-check. |
| Release gate | make release-check |
Validate environment and full gate before deployment. |
| Release command | make release DEPLOY_CMD="..." |
Run release checks first, then execute the deployment command. |
For command taxonomy and rationale, see Make commands and workflows.
Full command inventory
Auto-generated from `Makefile` help output (source of truth).
| Command | Purpose |
|---|---|
make api-docs |
Regenerate Python API HTML only (pdoc → docs/api/; included in docs-fix) |
make changelog-draft |
Draft from $(CHANGELOG_SINCE)..$(CHANGELOG_HEAD) → $(CHANGELOG_DRAFT) (merge into CHANGELOG.md by hand) |
make container-start |
Same migrate + uvicorn as Docker (scripts/container_entrypoint.sh; reads .env) |
make contract-test |
Stricter: generated OpenAPI must equal baseline JSON exactly |
make dead-code-check |
Run Vulture (unused code; see ADR 0014; not in verify-ci) |
make deps-audit |
Scan requirements.txt with pip-audit (OSV); fails on known CVEs |
make docker-build |
Build image study-app-api:local (requires Docker) |
make docs-check |
Verify docs are already in sync (fails on drift) |
make docs-fix |
Auto-update docs (UML + markers + md→html + format + pdoc API + search index) |
make env-check |
Verify env, deps, and DB connectivity |
make env-init |
Create .env from env/example (once per machine) |
make fix |
Run auto-fixes (format-fix + lint-fix + docs-fix) |
make format-check |
Verify code formatting (no changes) |
make format-fix |
Auto-format Python code |
make install |
Install dependencies |
make lint-check |
Run Ruff lint checks |
make lint-fix |
Run Ruff with auto-fixes |
make llm-ping |
Smoke-test LLM API (same env as changelog-draft) |
make logging-down |
Stop logging stack |
make logging-es-query |
Query ES for study-app logs (optional QUERY=<uuid>) |
make logging-reset |
Stop stack, delete ES volume + ./logs/*.log (clean slate) |
make logging-smoke |
Check Elasticsearch and Kibana URLs |
make logging-up |
Start ES/Kibana/Filebeat (use LOG_FORMAT=json, ./logs) |
make migrate |
Apply all Alembic migrations |
make migration name=… |
Auto-generate new Alembic migration |
make observability-down |
Stop Prometheus/Grafana stack |
make observability-smoke |
Check observability links return HTTP 200 |
make observability-up |
Start Prometheus/Grafana stack with Docker Compose |
make openapi-accept-changes |
Overwrite baseline with current app.openapi() (commit the file) |
make openapi-check |
Lint (operationId, summary, write+422 examples) + breaking-change |
make pre-commit-check |
Run all pre-commit hooks |
make pre-commit-install |
Install git pre-commit hooks |
make release DEPLOY_CMD='…' |
Run release-check then deploy command |
make release-check |
Run env-check + deps-audit + verify before deploy |
make requirements |
Auto-generate requirements.txt from .venv |
make run |
Start FastAPI dev server |
make run-loadtest-api |
Start API (high rate limit) → run tools.load_testing.runner → stop |
make run-loadtest-api-serve |
Like run, but high API rate limit (foreground; use in 2nd terminal with runner) |
make run-project |
Start observability stack (Prometheus/Grafana/…) + FastAPI |
make test |
Run full test suite (pytest + coverage per pyproject.toml) |
make test-one path=… |
Run one test file or node |
make test-warnings |
Run tests with full warning details |
make type-check |
Run mypy type checks |
make uml-check |
Verify docs/uml/rendered/*.svg match docs/uml/**/*.puml (no writes) |
make venv |
Create virtual environment |
make verify |
Run lint-check + type-check + openapi-check + contract-test + test + docs-fix |
make verify-ci |
Run deps-audit + lint-check + type-check + openapi-check + contract-test + test + docs-check |
Page history
| Date | Change | Author |
|---|---|---|
| Added Page history section (repository baseline). | Ivan Boyarkin |