|
| 1 | +# Falcon Agent Guide |
| 2 | + |
| 3 | +Read `CONTRIBUTING.md` first. Treat `pyproject.toml` and `tox.ini` as the |
| 4 | +executable source of truth when prose and configuration differ. In accordance |
| 5 | +with the “Use of LLMs” policy in `CONTRIBUTING.md`, carefully review and test |
| 6 | +all generated changes. |
| 7 | + |
| 8 | +## Repository map |
| 9 | + |
| 10 | +- `falcon/app.py`, `falcon/request.py`, and `falcon/response.py` implement the |
| 11 | + WSGI side. `falcon/asgi/` implements ASGI and WebSocket behavior. Shared |
| 12 | + behavior lives in modules such as `falcon/app_helpers.py`, `falcon/routing/`, |
| 13 | + `falcon/media/`, and `falcon/util/`. |
| 14 | +- `falcon/testing/` contains public test helpers. Primary tests live in |
| 15 | + `tests/`, with ASGI-specific coverage in `tests/asgi/`. Tutorial and example |
| 16 | + suites have dedicated tox environments. |
| 17 | +- `falcon/cyutil/*.pyx` contains optional optimized implementations selected by |
| 18 | + Python fallbacks such as `falcon/util/reader.py` and `falcon/util/uri.py`. |
| 19 | + Preserve both modes when changing these paths, and use a Cython tox |
| 20 | + environment. |
| 21 | +- Documentation is reStructuredText under `docs/`. Put runnable recipe snippets |
| 22 | + in `examples/recipes/`; documentation includes them with `literalinclude`. |
| 23 | + |
| 24 | +## Change rules |
| 25 | + |
| 26 | +- Keep patches narrow. Preserve Falcon's public API compatibility, HTTP/RFC |
| 27 | + correctness, and Python 3.9+ support on CPython and PyPy unless the task |
| 28 | + explicitly changes those contracts. |
| 29 | +- Check both WSGI and ASGI surfaces when shared request, response, routing, |
| 30 | + middleware, media, error, or testing behavior changes. Add or update the |
| 31 | + corresponding tests; do not assume inheritance makes behavior identical. |
| 32 | +- Maintain 100% branch coverage for changed behavior, including error and |
| 33 | + version-specific paths. Do not add production dependencies casually; |
| 34 | + `[project].dependencies` is currently empty. |
| 35 | +- Treat request and response hot paths as performance-sensitive. Reuse existing |
| 36 | + helpers. When throughput or allocation behavior could change, benchmark with |
| 37 | + `tox -e py310_bench -- <falcon-bench args>`. |
| 38 | +- Do not bulk-modernize `%` formatting in `falcon/`. `pyproject.toml` |
| 39 | + deliberately ignores Ruff's `UP030`, `UP031`, and `UP032` there pending |
| 40 | + inspection and benchmarks. |
| 41 | + |
| 42 | +## Style |
| 43 | + |
| 44 | +- Ruff targets Python 3.9, 88 columns, and single quotes. |
| 45 | +- Public classes, attributes, methods, and functions require |
| 46 | + Napoleon/Google-style docstrings. Start immediately after the opening quotes |
| 47 | + with a roughly 70-character summary that ends in a period. |
| 48 | +- Name caught exceptions `ex`. Limit single-character names to trivial indices |
| 49 | + and standard formulas. |
| 50 | +- Format necessary non-trivial tagged comments as |
| 51 | + `TODO|NOTE|PERF|APPSEC(<GitHub handle>):`. If the author's handle is |
| 52 | + unavailable, do not invent one and don't impersonate other users; |
| 53 | + avoid the tagged comment unless necessary. |
| 54 | + |
| 55 | +## Verification |
| 56 | + |
| 57 | +Run commands from the repository root. Start with the focused test, run only |
| 58 | +affected specialized environments next, and reserve the complete `tox` gate |
| 59 | +for broad or final validation. |
| 60 | + |
| 61 | +- In an already-prepared development environment, get focused feedback with |
| 62 | + `pytest tests/test_<area>.py -k '<case>'` or |
| 63 | + `pytest tests/asgi/test_<area>.py -k '<case>'`. |
| 64 | +- Run all Python tests and collect coverage data with `tox -e pytest`; check |
| 65 | + minimum-dependency compatibility with `tox -e mintest`; verify optional |
| 66 | + Cython behavior with a matching environment such as `tox -e py312_cython`. |
| 67 | +- Check formatting and lint with `tox -e ruff,pep8,pep8-docstrings`. Apply |
| 68 | + formatting and safe fixes only with `tox -e reformat`. |
| 69 | +- For typing changes, run `tox -e mypy,mypy_tests`. For documentation or |
| 70 | + docstring changes, run `tox -e docs`. |
| 71 | +- Run `tox` for the complete local gate and 100% combined coverage report. |
| 72 | + |
| 73 | +## Documentation and changelog |
| 74 | + |
| 75 | +- Update user and API documentation when behavior or public contracts change; |
| 76 | + build it with `tox -e docs`. |
| 77 | +- Functionality changes require |
| 78 | + `docs/_newsfragments/{issue_number}.{fragment_type}.rst`. The exact fragment |
| 79 | + types are `breakingchange`, `newandimproved`, `bugfix`, and `misc`. Preview |
| 80 | + the result with `tox -e changelog_draft`. |
| 81 | +- Never invent an issue or PR number. If none is available, report that the |
| 82 | + fragment cannot be named instead of creating a placeholder. |
| 83 | +- For recipes, put executable code in `examples/recipes/`, include it from |
| 84 | + `docs/user/recipes/`, and add coverage in `tests/test_recipes.py` when |
| 85 | + practical. |
| 86 | + |
| 87 | +## Operator boundaries |
| 88 | + |
| 89 | +- Never create, submit, or open a GitHub pull request. Prepare the changes and |
| 90 | + verification evidence, then ask the human operator to open the pull request. |
| 91 | +- Never tick, check, or otherwise complete a pull request checklist on the |
| 92 | + operator's behalf. The human operator must review the changes and complete |
| 93 | + every checklist item manually. |
| 94 | + |
| 95 | +See `CONTRIBUTING.md` for commit-message format, full docstring markup rules, |
| 96 | +review policy, and contributor conduct. |
0 commit comments