gistfile1.txt

# Pageantry Project Guidelines

## Context

- This project should never be directly installed. Python, pip, and project
dependencies should be only executed inside Docker containers.

## Build & Test Commands

- **Run Tests**: `docker compose run --rm pytest`
- **Run Single Test**: `docker compose run --rm pytest python -m pytest tests/test_file.py::test_name`
- **Test with Coverage**: `docker compose run --rm pytest python -m pytest --cov=pageantry`
- **Run Development Server**: `docker compose up -d app`

## Code Style Guidelines

- **Formatting**: Use Black for code formatting
- **Linting**: Use pycodestyle for linting
- **Type Hints**: Use type hints for all function parameters and return values
- **Imports**:
  - Standard lib imports first, third-party second, local modules third
  - Use absolute imports from the package root
- **Naming**:
  - Classes: PascalCase
  - Functions/Variables: snake_case
  - Constants: UPPER_SNAKE_CASE
- **Error Handling**: Use context-specific exceptions and handle them explicitly
- **Documentation**: Docstrings for all modules, classes, and functions (Google style)
- **Architecture**: Follow application factory pattern for Starlette apps
- **Whitespace**: Blank lines should not contain whitespace

## Git Commit Guidelines

- Follow Angular commit message format: `<type>(<scope>): <short summary>`
- Types:
  - build: Changes that affect the build system or external dependencies
  - ci: Changes to CI configuration files and scripts
  - docs: Documentation only changes
  - feat: A new feature
  - fix: A bug fix
  - perf: A code change that improves performance
  - refactor: A code change that neither fixes a bug nor adds a feature
  - test: Adding missing tests or correcting existing tests
- Example: `feat(models): add SQLAlchemy ORM models`

## Git Workflow

- **IMPORTANT**: Never push directly to the main branch without explicit permission
- Create feature branches for all changes using format: `<username>/<type>/<description>`
- Example branch name: `lyndsysimon/feat/add-user-dashboard`
- Push to feature branches first, then open pull requests to merge into main

## Assistant Instructions

- When asked to remember instructions or facts about the project, suggest updates to this file.
- Keep this documentation up-to-date as a reference for project guidelines and conventions.
- Use this file as the source of truth for project configurations and procedures.