diff --git a/docs/Red Panda Standards_Django_V1-01.md b/docs/Red Panda Standards_Django_V1-01.md new file mode 100644 index 0000000..9645409 --- /dev/null +++ b/docs/Red Panda Standards_Django_V1-01.md @@ -0,0 +1,341 @@ +# Red Panda Approvalβ„’ β€” Django Addendum + +**Owner:** Robert Helewka <r@helu.ca> +**Version:** 1.01 +**Last reviewed:** 2026-04-18 +**Parent document:** [Red_Panda_Standards_V1-00.md](Red_Panda_Standards_V1-00.md) + +This document extends the main Red Panda Standards with Django-specific conventions. Where the two documents overlap, the **main standard governs** β€” this addendum only adds Django-specific detail or explicitly-noted exceptions. + +## 🐾 Red Panda Approvalβ„’ + +This project follows Red Panda Approval standards β€” our gold standard for Django application quality. Code must be elegant, reliable, and maintainable to earn the approval of our adorable red panda judges. + +### The 5 Sacred Django Criteria +1. **Fresh Migration Test** β€” Clean migrations from empty database +2. **Elegant Simplicity** β€” No unnecessary complexity +3. **Observable & Debuggable** β€” Proper logging and error handling +4. **Consistent Patterns** β€” Follow Django conventions +5. **Actually Works** β€” Passes all checks and serves real user needs + +## Environment Standards +- Virtual environment: ~/env/PROJECT/bin/activate +- Use pyproject.toml for project configuration (no setup.py, no requirements.txt) +- Python version: specified in pyproject.toml +- Dependencies: floor-pinned with ceiling (e.g. `Django>=5.2,<6.0`) + +### Dependency Pinning + +```toml +# Correct β€” floor pin with ceiling +dependencies = [ + "Django>=5.2,<6.0", + "djangorestframework>=3.14,<4.0", + "cryptography>=41.0,<45.0", +] + +# Wrong β€” exact pins in library packages +dependencies = [ + "Django==5.2.7", # too strict, breaks downstream +] +``` + +Exact pins (`==`) are only appropriate in application-level lock files, not in reusable library packages. + +## Directory Structure +myproject/ # Git repository root +β”œβ”€β”€ .gitignore +β”œβ”€β”€ README.md +β”œβ”€β”€ pyproject.toml # Project configuration (moved to repo root) +β”œβ”€β”€ docker-compose.yml +β”œβ”€β”€ .env # Docker Compose environment +β”‚ # ANGELIA_DB_ENGINE=postgresql +β”‚ # ANGELIA_DB_NAME=angelia2 +β”‚ # ANGELIA_DB_USER=angelia +β”‚ # ANGELIA_DB_PASSWORD=changeme +β”‚ # ANGELIA_DB_HOST=db +β”‚ # ANGELIA_DB_PORT=5432 +β”œβ”€β”€ .env.example +β”‚ +β”œβ”€β”€ project/ # Django project root (manage.py lives here) +β”‚ β”œβ”€β”€ manage.py +β”‚ β”œβ”€β”€ Dockerfile +β”‚ β”œβ”€β”€ .env # Local development environment +β”‚ β”‚ # ANGELIA_DB_ENGINE=sqlite +β”œβ”€β”€ .env.example +β”‚ +β”œβ”€β”€ config/ # Django configuration module +β”‚ β”‚ β”œβ”€β”€ __init__.py +β”‚ β”‚ β”œβ”€β”€ settings.py +β”‚ β”‚ β”œβ”€β”€ urls.py +β”‚ β”‚ β”œβ”€β”€ wsgi.py +β”‚ β”‚ └── asgi.py +β”‚ β”‚ +β”‚ β”œβ”€β”€ accounts/ # Django app +β”‚ β”‚ β”œβ”€β”€ __init__.py +β”‚ β”‚ β”œβ”€β”€ models.py +β”‚ β”‚ β”œβ”€β”€ views.py +β”‚ β”‚ └── urls.py +β”‚ β”‚ +β”‚ β”œβ”€β”€ blog/ # Django app +β”‚ β”‚ β”œβ”€β”€ __init__.py +β”‚ β”‚ β”œβ”€β”€ models.py +β”‚ β”‚ β”œβ”€β”€ views.py +β”‚ β”‚ └── urls.py +β”‚ β”‚ +β”‚ β”œβ”€β”€ static/ +β”‚ β”‚ β”œβ”€β”€ css/ +β”‚ β”‚ └── js/ +β”‚ β”‚ +β”‚ └── templates/ +β”‚ └── base.html +β”‚ +β”œβ”€β”€ web/ # Nginx configuration +β”‚ └── nginx.conf +β”‚ +β”œβ”€β”€ db/ # PostgreSQL configuration +β”‚ └── postgresql.conf +β”‚ +└── docs/ # Project documentation + └── index.md + +## Settings Structure +- Use a single settings.py file +- Use django-environ or python-dotenv for environment variables +- Never commit .env files to version control +- Provide .env.example with all required variables documented +- Create .gitignore file +- Create a .dockerignore file + +## Environment Variables + +All env vars in `.env` MUST use the `SERVICENAME_` prefix (per main standard). The examples below use `ANGELIA_` β€” substitute the actual service name for your app. + +### PostgreSQL settings (only if `SERVICENAME_DB_ENGINE=postgresql`) +``` +ANGELIA_DB_NAME=angelia2 +ANGELIA_DB_USER=angelia +ANGELIA_DB_PASSWORD=changeme +ANGELIA_DB_HOST=db +ANGELIA_DB_PORT=5432 +``` + +### Rules +- Never use `DATABASE_URL` or `dj-database-url` β€” always individual vars +- Never use unprefixed `DB_HOST` / `APP_DB_NAME` β€” always service-prefixed +- The Django `Settings` class declares each prefixed var explicitly so the full config is documented in one place +- `.env` is gitignored; `.env.example` with placeholder values is committed + +## Code Organization +- Imports: PEP 8 ordering (stdlib, third-party, local) +- Type hints on function parameters +- CSS: External .css files only (no inline styles, no embedded `