CONTRIBUTING.md

Contributing to GridCast

Thank you for your interest in contributing to GridCast! This document provides guidelines to ensure a smooth development workflow.

Development Setup

# Clone and setup
git clone https://github.com/knight22-21/GridCast.git
cd GridCast
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt
pre-commit install

Code Quality Standards

Linting & Formatting

We use Ruff for both linting and formatting:

ruff check src/ tests/ pipelines/     # Lint
ruff format src/ tests/ pipelines/    # Format

Testing

All changes must pass the existing test suite and maintain ≥80% coverage:

# Run all tests
pytest tests/ -v

# Run with coverage
pytest tests/ --cov=src --cov-report=term-missing

# Run specific test suites
pytest tests/unit/ -v
pytest tests/integration/ -v
pytest tests/data_validation/ -v

Pre-commit Hooks

Pre-commit hooks run automatically on git commit. To run them manually:

pre-commit run --all-files

Branch Strategy

1. Create a feature branch from main
2. Make your changes with clear commit messages
3. Ensure all tests pass and coverage ≥80%
4. Open a pull request against main
5. CI will run automatically on the PR

Project Conventions

• Configuration: All hyperparameters and paths go in params.yaml — never hardcode
• Secrets: All credentials use environment variables via .env — never commit secrets
• Blob Storage: All Azure Blob interactions include a local file fallback for offline development
• Time-series: Always use chronological splits, never random. Use shift() for lag features
• Type hints: All function signatures include type annotations
• Docstrings: All public functions have Google-style docstrings