From fa52e47cf678b6d574c6b5a588c5467212507115 Mon Sep 17 00:00:00 2001 From: Grey Li Date: Sat, 26 Sep 2026 13:42:08 +0800 Subject: [PATCH] Add repository instructions for coding agents --- AGENTS.md | 72 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 72 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..eadccee --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,72 @@ +# Working on Bootstrap-Flask + +Bootstrap-Flask provides Flask extension classes and Jinja macros for Bootstrap 4 +and 5. The distribution is `Bootstrap-Flask`; the Python package is +`flask_bootstrap`. Do not install `Flask-Bootstrap` in the same environment: both +projects use that package name. + +## Repository layout + +- `flask_bootstrap/__init__.py`: extension initialization, configuration, asset + loading, and Python helpers. +- `flask_bootstrap/templates/base/`: shared macros. `bootstrap4/` and `bootstrap5/` + contain version-specific macros and wrappers; `bootstrap/` is the deprecated + Bootstrap 4 compatibility path. +- `flask_bootstrap/static/`: bundled Bootstrap, Bootswatch, Popper, jQuery, and icon + assets, separated by Bootstrap version. +- `tests/`: pytest tests, with shared fixtures in `conftest.py` and extension + fixtures in `test_bootstrap4/` and `test_bootstrap5/`. +- `docs/`: Sphinx documentation in reStructuredText. `examples/bootstrap4/` and + `examples/bootstrap5/` contain runnable demo applications. +- `pyproject.toml`, `MANIFEST.in`, and `CHANGES.rst`: package metadata, packaged + assets, and release history. `tox.ini` and `.github/workflows/` define checks. + +## Development and validation + +Use Python 3.11 or newer; the current test matrix covers 3.11 through 3.14. From +the repository root, the development setup documented in `docs/index.rst` is: + +```sh +python3 -m venv venv +. venv/bin/activate +python -m pip install -e . +python -m pip install -r requirements/dev.txt +``` + +Reuse an existing suitable environment when available. Run checks appropriate to +the change: + +```sh +python -m pytest # full test suite +python -m pytest tests/test_bootstrap5/test_render_form.py # focused example +tox -e flake8 # Python style checks +tox -e docs # Sphinx, warnings as errors +tox # configured full checks +``` + +Tox skips unavailable Python interpreters, so report what actually ran. The +coverage environment is currently spelled `covarage`: use `tox -e covarage` when +checking coverage. CI tests Linux, macOS, and Windows. + +## Making changes + +- Check both Bootstrap versions when changing shared behavior. Form macros have + separate implementations; shared table, navigation, pagination, and utility + changes may affect both versions through inheritance or imports. Preserve + version-specific markup instead of copying Bootstrap 5 classes into Bootstrap 4. +- Follow existing pytest fixtures and HTML assertions. For behavior changes, + add focused regression coverage in the relevant version suites and run related + tests before the full suite. +- Keep public macro arguments, configuration keys, and compatibility wrappers in + mind. Document public behavior changes in the relevant `docs/` pages and + describe user-visible changes in `CHANGES.rst`. +- Follow `.flake8`: maximum Python line length is 119 and maximum complexity is + 7. Preserve existing license notices in inherited macros. +- Requirement `.txt` files are generated by `pip-compile-multi`. Edit the + corresponding `requirements/*.in` sources and regenerate intentionally; avoid + unrelated dependency churn. +- For asset updates, check version constants, CDN URLs, integrity values, bundled + files, and local-serving behavior together. Ensure new templates and static + assets remain covered by `MANIFEST.in`. +- Keep changes scoped to the requested task. In the handoff or pull request, + explain the resulting behavior, checks performed, and any checks not run.