2.8 KiB
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:
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.