Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
142 lines (94 loc) · 3.29 KB

CONTRIBUTING.md

File metadata and controls

142 lines (94 loc) · 3.29 KB

Contributing

Prerequisites

  • Python >=3.12
  • UV package manager

Getting Setup

The fastsandpm tool chain uses uv as its packaging and tool running utility.

Development Workflow

Testing - pytest

Unit tests validate functionality and are stored in the ./tests/ directory.

uv run pytest              # Run all unit tests
uv run pytest tests/test_module.py::test_function  # Run specific test

Type Checking - mypy

Catches type-related errors at development time, ensuring code reliability.

uv run mypy

Code Quality - ruff

Enforces PEP8 compliance and catches common bugs automatically.

uv run ruff check         # Check code style
uv run ruff check --fix   # Auto-fix style issues

Integration Testing - tox

Runs all test suites across Python versions and environments to ensure compatibility.

uv run tox               # Run all test suites
uv run tox p             # Run tests in parallel (faster)

Code Formatting Guidelines

All Python code must comply with PEP 8.

Project-specific settings are configured in pyproject.toml:

  • Line length: 100 characters
  • Python version: 3.12+
  • Import sorting: enabled (isort)
  • Quote style: double quotes

Branching and Commit Conventions

Branch Naming

Use the following format for branch names:

  • feature/* - New features (e.g., feature/add-export-functionality)
  • bugfix/* - Bug fixes (e.g., bugfix/fix-yaml-parsing)
  • docs/* - Documentation updates
  • chore/* - Maintenance tasks

Commit Messages

Use the following format for commit messages:

(BREAKING) description

Optional body with more details

Where the BREAKING part is only appended for breaking API changes which will require a major version bump.

Before Making a PR

Ensure all of the following are complete:

  • All tests pass: uv run tox (or uv run tox p for parallel)
    • Code is formatted: uv run ruff check --fix
    • Type checking passes: uv run mypy
  • CHANGELOG.md updated with your changes
  • Documentation updated (docstrings, README, docs/)
  • Branch follows naming convention: feature/*, bugfix/*, etc.
  • Commit messages follow Conventional Commits format
  • PR description clearly explains the changes and motivation

Debugging Tips

Running Specific Tests

# Run tests matching a pattern
uv run pytest -k "pattern"

# Run with verbose output
uv run pytest -v

# Show print statements
uv run pytest -s

# Stop on first failure
uv run pytest -x

Type Checking with Details

# Show detailed error information
uv run mypy --show-error-codes --show-error-context

Building Documentation Locally

uv run tox -e docs_html   # Build HTML docs
uv run tox -e docs_dirhtml # Build dirhtml docs

Common Issues and Troubleshooting

UV Command Not Found

  • Ensure uv is installed and in your PATH
  • Try python -m pip install uv
  • Check with your VDT team if using module-based installation

Import Errors When Running Tests

  • Ensure you're running commands with uv run (not directly)
  • Try: uv sync to update dependencies

Tests Pass Locally but Fail in CI

  • Run the full test suite: uv run tox (not just pytest)
  • Check Python version: python --version (must be 3.12+)