Development Guidelines

This document contains critical information about working with this codebase. Follow these guidelines precisely.

Core Development Rules

Package Management
- Use uv, or pip if uv doesn't work.
- Installation: uv add package
- Running tools: uv run tool
- Upgrading: uv add --dev package --upgrade-package package
- FORBIDDEN: uv pip install, @latest syntax
Code Quality
- Type hints required for all code
- Public APIs must have docstrings
- Functions must be focused and small
- Follow existing patterns exactly
- Line length: 88 chars maximum
Testing Requirements
- Framework: uv run pytest
- Async testing: use anyio, not asyncio
- Coverage: test edge cases and errors
- New features require tests
- Bug fixes require regression tests
Code Style
- PEP 8 naming (snake_case for functions/variables)
- Class names in PascalCase
- Constants in UPPER_SNAKE_CASE
- Document with docstrings
- Use f-strings for formatting

For commits fixing bugs or adding features based on user reports add:
```
git commit --trailer "Reported-by:<name>"
```
Where <name> is the name of the user.

For commits related to a Github issue, add

git commit --trailer "Github-Issue:#<number>"

NEVER ever mention a co-authored-by or similar aspects. In particular, never mention the tool used to create the commit message or PR.

Development Philosophy

Simplicity: Write simple, straightforward code
Readability: Make code easy to understand
Performance: Consider performance without sacrificing readability
Maintainability: Write code that's easy to update
Testability: Ensure code is testable
Reusability: Create reusable components and functions
Less Code = Less Debt: Minimize code footprint

Coding Best Practices

Early Returns: Use to avoid nested conditions
Descriptive Names: Use clear variable/function names (prefix handlers with "handle")
Constants Over Functions: Use constants where possible
DRY Code: Don't repeat yourself
Functional Style: Prefer functional, immutable approaches when not verbose
Minimal Changes: Only modify code related to the task at hand
Function Ordering: Define composing functions before their components
TODO Comments: Mark issues in existing code with "TODO:" prefix
Simplicity: Prioritize simplicity and readability over clever solutions
Build Iteratively Start with minimal functionality and verify it works before adding complexity
Run Tests: Test your code frequently with realistic inputs and validate outputs
Build Test Environments: Create testing environments for components that are difficult to validate directly
Functional Code: Use functional and stateless approaches where they improve clarity
Clean logic: Keep core logic clean and push implementation details to the edges
File Organsiation: Balance file organization with simplicity - use an appropriate number of files for the project scale

System Architecture

This project is a web app for storing inspection reports. The user interface is provided over https, and the back-end data storage is provided by SQLite, with python providing the logic. There is an Admin account who can create and remove users. A login is required to access the app. All users have the ability to create, edit and delete inspection reports. The reports are accessible via an index page, which allows for existing reports to be accessed, updated and printed as PDF documents, as well as for new reports to be created. Within each report, the following header fields are required:

Report number, generated by the app
EDMS number, an external reference to be added by the user
Inspection conducted by, the field where the name of the user is displayed
Date of the inspection, to be entered when the report is being created
Status, which has one of three values: No comments, Minor comments or Major comments.

Core Components

config.py: Configuration management
app.py: Main daemon which runs the app Additional components as needed.

Pull Requests

Create a detailed message of what changed. Focus on the high level description of the problem it tries to solve, and how it is solved. Don't go into the specifics of the code unless it adds clarity.
Always add pingud98 as reviewer.
NEVER ever mention a co-authored-by or similar aspects. In particular, never mention the tool used to create the commit message or PR.

Python Tools

Code Formatting

Ruff
- Format: uv run ruff format .
- Check: uv run ruff check .
- Fix: uv run ruff check . --fix
- Critical issues:
  - Line length (88 chars)
  - Import sorting (I001)
  - Unused imports
- Line wrapping:
  - Strings: use parentheses
  - Function calls: multi-line with proper indent
  - Imports: split into multiple lines
Type Checking
- Tool: uv run pyright
- Requirements:
  - Explicit None checks for Optional
  - Type narrowing for strings
  - Version warnings can be ignored if checks pass
Pre-commit
- Config: .pre-commit-config.yaml
- Runs: on git commit
- Tools: Prettier (YAML/JSON), Ruff (Python)
- Ruff updates:
  - Check PyPI versions
  - Update config rev
  - Commit config first

Error Resolution

CI Failures
- Fix order:
  1. Formatting
  2. Type errors
  3. Linting
- Type errors:
  - Get full line context
  - Check Optional types
  - Add type narrowing
  - Verify function signatures
Common Issues
- Line length:
  - Break strings with parentheses
  - Multi-line function calls
  - Split imports
- Types:
  - Add None checks
  - Narrow string types
  - Match existing patterns
Best Practices
- Check git status before commits
- Run formatters before type checks
- Keep changes minimal
- Follow existing patterns
- Document public APIs
- Test thoroughly

6 KiB Raw Blame History