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..d91f9ec --- /dev/null +++ b/docs/Red Panda Standards_Django_V1-01.md @@ -0,0 +1,324 @@ +## 🐾 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 +β”‚ # DB_ENGINE=postgresql +β”‚ # APP_DB_NAME=angelia2 +β”‚ # APP_DB_USER=angelia +β”‚ # APP_DB_PASSWORD=changeme +β”‚ # DB_HOST=db +β”‚ # DB_PORT=5432 +β”œβ”€β”€ .env.example +β”‚ +β”œβ”€β”€ project/ # Django project root (manage.py lives here) +β”‚ β”œβ”€β”€ manage.py +β”‚ β”œβ”€β”€ Dockerfile +β”‚ β”œβ”€β”€ .env # Local development environment +β”‚ β”‚ # 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 + +### PostgreSQL settings (only if DB_ENGINE=postgresql) +``` +APP_DB_NAME=angelia2 +APP_DB_USER=angelia +APP_DB_PASSWORD=changeme +DB_HOST=db +DB_PORT=5432 +``` + +## 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 `