Development Guide

Contributing to NHL Scrabble Score Analyzer.

Quick Links for Contributors

Getting Started

How to Contribute Code: Complete workflow for submitting code contributions
How to Setup Pre-commit Hooks: Configure 55 automated quality checks

Testing

How to Run Tests: Run tests with pytest, tox, and coverage
Testing Philosophy: Understand the testing strategy and quality goals

Architecture

Architecture Overview: System design and component organization
NHL API Strategy: NHL API integration approach

Additional Resources

Makefile Documentation: 55 Makefile targets for automation
Your First Contribution to NHL Scrabble: Step-by-step first contribution tutorial

Development Setup

Quick Start

# Clone repository
git clone https://github.com/bdperkin/nhl-scrabble.git
cd nhl-scrabble

# Setup with UV (10-100x faster)
make uv-init
source .venv/bin/activate

# Or standard setup
make init
source .venv/bin/activate

# Verify setup
make check

Testing

# Quick test run
pytest

# With coverage
make test-cov

# All Python versions (uses tox-uv automatically)
make tox

# Parallel testing (10x faster)
make tox-parallel

Code Quality

# Run all quality checks
make quality

# Individual checks
make ruff-check
make ruff-format
make mypy

# Pre-commit hooks (55 checks)
make pre-commit

Code Style Standards

PEP 8 - Python style guide (line length: 100)
Type hints - All functions annotated (mypy strict mode)
Docstrings - 100% coverage required (Google style)
Ruff - ALL rules enabled (comprehensive linting)
Pre-commit hooks - 55 automated checks before commit

Example Code

def calculate_score(text: str) -> int:
    """Calculate Scrabble score for text.

    Args:
        text: Input text to score (case-insensitive).

    Returns:
        Total score as sum of letter values.

    Example:
        >>> calculate_score("HELLO")
        8

    Raises:
        ValueError: If text is empty.
    """
    if not text:
        raise ValueError("Text cannot be empty")

    return sum(SCRABBLE_VALUES.get(char.upper(), 0) for char in text)

Contributing Workflow

Fork repository on GitHub
Create feature branch: git checkout -b feature/my-feature
Make changes with tests
Run quality checks: make check
Commit with conventional commits (see below)
Push and create pull request
Respond to review feedback

Commit Message Format

Follow conventional commits:

<type>(<scope>): <subject>

<body>

<footer>

Types: feat, fix, docs, test, refactor, perf, chore, ci, build

Examples:

feat(api): Add retry logic for NHL API requests
fix(scoring): Handle special characters in player names
docs(tutorials): Update installation guide
test(processors): Add playoff calculator edge cases

Building Documentation

# Build HTML docs
make docs

# Auto-rebuild on changes
sphinx-autobuild docs docs/_build/html

# Serve locally
make serve-docs
# Visit http://localhost:8000

# Check spelling
tox -e docs -- -b spelling

# Check links
sphinx-build -b linkcheck docs docs/_build/linkcheck

Release Process

Ensure main branch is clean and up to date
Update CHANGELOG.md with release notes
Run full test suite: make tox-parallel
Run CI simulation: make ci
Tag release: git tag -a v0.1.0 -m "Release v0.1.0"
Push tag: git push --tags
GitHub Actions builds and publishes to PyPI automatically

Note: Version is dynamically determined from git tags (hatch-vcs), no manual version updates needed.

Project Resources

Repository: https://github.com/bdperkin/nhl-scrabble
Issues: https://github.com/bdperkin/nhl-scrabble/issues
Pull Requests: https://github.com/bdperkin/nhl-scrabble/pulls
Discussions: https://github.com/bdperkin/nhl-scrabble/discussions
CI/CD: https://github.com/bdperkin/nhl-scrabble/actions

Development Tools

UV Package Manager (10-100x faster): See How to Use UV Package Manager for details
Tox-UV Integration (10x faster testing): Automatic when using tox, see Makefile Documentation
Pre-commit-UV (9x faster hooks): Automatic with pre-commit, see How to Setup Pre-commit Hooks
Makefile (55 documented targets): Complete automation, see Makefile Documentation

Community

Code of Conduct: Be respectful and inclusive
Security Policy: See SECURITY.md for vulnerability reporting
Support: GitHub Discussions for questions
Contributing: See CONTRIBUTING.md for detailed guidelines