Skip to content

Latest commit

 

History

History
318 lines (243 loc) · 7.58 KB

pre-commit-setup.md

File metadata and controls

318 lines (243 loc) · 7.58 KB

Pre-commit Setup and Usage Guide

This guide covers the setup and usage of pre-commit hooks in the Gadugi project.

Quick Setup

For UV Projects (Recommended)

# Install pre-commit hooks
uv run pre-commit install

# Run hooks on all files (verify setup)
uv run pre-commit run --all-files

For Standard Python Projects

# Install pre-commit hooks
pre-commit install

# Run hooks on all files (verify setup)
pre-commit run --all-files

What Pre-commit Hooks Do

Our pre-commit configuration automatically runs these checks:

Code Quality

  • ruff: Python linting with auto-fixes
  • ruff-format: Code formatting
  • debug-statements: Removes debug print statements
  • pyright: Type checking (runs on push)

File Quality

  • trailing-whitespace: Removes trailing spaces
  • end-of-file-fixer: Ensures files end with newline
  • check-yaml: Validates YAML syntax
  • check-merge-conflict: Detects merge conflict markers

Security

  • detect-secrets: Finds potential secrets in code

Testing (on push)

  • pytest: Runs test suite before pushing
  • pyright: Type checking validation

Usage

Automatic Usage

Once installed, hooks run automatically:

git commit -m "Your commit message"
# Hooks run automatically before commit

Manual Usage

Run hooks manually anytime:

# Run all hooks on changed files
uv run pre-commit run  # UV projects
pre-commit run         # Standard projects

# Run all hooks on all files
uv run pre-commit run --all-files  # UV projects
pre-commit run --all-files         # Standard projects

# Run specific hook
uv run pre-commit run ruff          # UV projects
pre-commit run ruff                 # Standard projects

# Run type checking specifically (pre-push stage)
uv run pre-commit run pyright --hook-stage pre-push  # UV projects
pre-commit run pyright --hook-stage pre-push         # Standard projects

Troubleshooting

Installation Issues

Hook installation failed:

# Reinstall hooks
uv run pre-commit uninstall
uv run pre-commit install

Pre-commit command not found:

# For UV projects - pre-commit should be in pyproject.toml
uv sync --all-extras

# For standard projects - install pre-commit
pip install pre-commit

Hook Execution Issues

Hooks failing on commit:

# See detailed output
uv run pre-commit run --all-files --verbose

# Skip hooks temporarily (not recommended)
git commit -m "message" --no-verify

Specific hook failing:

# Run individual hook to see details
uv run pre-commit run ruff --verbose
uv run pre-commit run trailing-whitespace --verbose

# Debug pyright type checking issues
uv run pre-commit run pyright --hook-stage pre-push --verbose
pyright container_runtime/  # Run pyright on specific directory

Configuration Updates

Update hook versions:

# Update to latest versions
uv run pre-commit autoupdate

# Commit the updated .pre-commit-config.yaml
git add .pre-commit-config.yaml
git commit -m "Update pre-commit hook versions"

Configuration Reference

Our .pre-commit-config.yaml configuration:

repos:
  # Python code quality
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.8.4
    hooks:
      - id: ruff
        args: [ --fix ]  # Auto-fix issues where possible
      - id: ruff-format

  # General file quality
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v5.0.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-yaml
      - id: check-added-large-files
        args: ['--maxkb=1000']
      - id: check-case-conflict
      - id: check-merge-conflict
      - id: check-toml
      - id: debug-statements
      - id: mixed-line-ending
        args: ['--fix=lf']

  # Security scanning
  - repo: https://github.com/Yelp/detect-secrets
    rev: v1.5.0
    hooks:
      - id: detect-secrets
        args: ['--baseline', '.secrets.baseline']
        exclude: .*\.lock$|package-lock\.json$

  # Type checking (runs on push)
  - repo: local
    hooks:
      - id: pyright
        name: pyright type checker
        entry: pyright
        language: system
        types: [python]
        pass_filenames: false
        stages: [pre-push]

  # Testing (runs on push, not commit)
  - repo: local
    hooks:
      - id: pytest
        name: pytest
        entry: uv run pytest  # Use 'pytest' for non-UV projects
        language: system
        pass_filenames: false
        always_run: true
        stages: [pre-push]

# Global settings
default_language_version:
  python: python3.13

default_stages: [pre-commit, pre-push]

# Files to exclude from all hooks
exclude: |
  (?x)^(
    .*\.skip$|
    \.venv/.*|
    venv/.*|
    \.git/.*|
    \.pytest_cache/.*|
    __pycache__/.*|
    \.worktrees/.*
  )

Best Practices

For Developers

  1. Install hooks immediately after cloning repository
  2. Run manually before important commits
  3. Don't skip hooks unless absolutely necessary
  4. Fix issues rather than bypassing checks
  5. Update regularly to get latest improvements

For Teams

  1. Standardize on UV for consistent tooling
  2. Document exceptions when hooks must be skipped
  3. Review hook failures in code reviews
  4. Update configurations as project needs evolve
  5. Monitor hook performance to prevent slow commits

Integration with Workflows

Pre-commit hooks integrate with our development workflow:

  • Phase 6 Testing: Agents verify all hooks pass
  • PR Creation: Hooks must pass before PR creation
  • Code Review: Hook failures prevent PR approval
  • CI/CD: Hooks run again in continuous integration

This ensures consistent code quality across all development activities.

Pyright Type Checking

Overview

Pyright provides static type checking for Python code, helping catch type-related errors before runtime. It's configured to run during the pre-push stage to avoid slowing down commits.

Configuration

Pyright is configured via pyrightconfig.json:

{
  "typeCheckingMode": "standard",
  "pythonVersion": "3.11",
  "pythonPlatform": "All",
  "reportMissingImports": "warning",
  "reportMissingTypeStubs": "none",
  "include": ["**/*.py"],
  "exclude": [".venv", ".git", ".worktrees", "__pycache__"]
}

Key Features

  • Docker Import Handling: Uses TYPE_CHECKING guards for optional dependencies
  • Standard Mode: Balanced type checking that catches errors without being too strict
  • Import Warnings: Reports missing imports but allows development flexibility
  • CI Integration: Runs automatically on push to catch type issues early

Troubleshooting Type Issues

Common Docker Import Errors:

# ✅ Correct approach using TYPE_CHECKING
from typing import TYPE_CHECKING

if TYPE_CHECKING:
    import docker
else:
    docker = None

try:
    import docker  # type: ignore[import-untyped]
    docker_available = True
except ImportError:
    docker_available = False

Type Ignore Comments:

# Use specific ignore codes for better maintainability
docker.from_env()  # type: ignore[attr-defined]

Running Pyright Manually:

# Check specific files
pyright container_runtime/

# Get verbose output
pyright --verbose

# Generate statistics
pyright . --stats

Integration with Development Workflow

  1. Phase 6 Testing: WorkflowManager agents verify pyright passes
  2. Pre-push Hooks: Automatic type checking before code sharing
  3. PR Reviews: Type issues block PR approval
  4. CI/CD: Additional verification in continuous integration

This multi-layer approach ensures type safety without impeding development velocity.