35 lines
2.8 KiB
Markdown
35 lines
2.8 KiB
Markdown
# Repository Guidelines
|
|
|
|
## Project Structure & Module Organization
|
|
|
|
This repository is currently a minimal Flask template containing only `README.md`. As the application is introduced, keep production code in an `app/` package, with the application factory in `app/__init__.py`, route modules under `app/routes/`, templates in `app/templates/`, and browser assets in `app/static/`. Put automated tests in `tests/`, mirroring the source layout where practical. Keep one-off maintenance commands in `scripts/` rather than mixing them with application modules.
|
|
|
|
## Build, Test, and Development Commands
|
|
|
|
No dependency manifest or task runner is committed yet. When adding them, document the exact setup and execution commands in `README.md`. A conventional local workflow is:
|
|
|
|
```bash
|
|
python -m venv .venv
|
|
source .venv/bin/activate
|
|
pip install -r requirements.txt
|
|
flask --app app run --debug
|
|
pytest
|
|
```
|
|
|
|
Do not assume these commands work until the corresponding Flask package, requirements file, and tests have been added. Prefer `python -m <tool>` when it avoids ambiguity about which virtual environment is active.
|
|
|
|
## Coding Style & Naming Conventions
|
|
|
|
Use four spaces for Python indentation and follow PEP 8. Name modules, functions, and variables with `snake_case`; classes with `PascalCase`; constants with `UPPER_SNAKE_CASE`. Keep routes thin and move reusable business logic into focused service modules. Use descriptive template and endpoint names, such as `account/profile.html` and `account.profile`. If formatters or linters are introduced, commit their configuration and run them before submitting changes.
|
|
|
|
## Testing Guidelines
|
|
|
|
Use `pytest` for new tests. Name files `test_*.py` and test functions `test_<behavior>`. Place shared fixtures in `tests/conftest.py`, including an application configured for testing. Cover success paths, validation failures, and relevant HTTP status codes. Every bug fix should include a regression test. No coverage threshold is configured; avoid reducing coverage for code you touch.
|
|
|
|
## Commit & Pull Request Guidelines
|
|
|
|
The history currently contains only `first commit`, so no established convention exists. Use short, imperative commit subjects, for example `Add health check endpoint`, and keep unrelated changes separate. Pull requests should explain the purpose and approach, list verification commands, and link relevant issues. Include screenshots for visible template or styling changes, and call out configuration, migration, or deployment impacts.
|
|
|
|
## Security & Configuration
|
|
|
|
Never commit secrets, local virtual environments, or generated caches. Load environment-specific values from environment variables, provide safe placeholders in `.env.example`, and keep real `.env` files ignored. Validate user input and avoid exposing Flask debug mode outside local development.
|