Contributing to FIRM3D

We welcome contributions to FIRM3D! This document provides guidelines for contributing to the project.

Quick Start

  1. Set up development environment:

    pip install -e ".[dev]"
pre-commit install

  2. Run tests and checks:

    ruff check --fix .
ruff format .
python -m unittest discover tests/
cd docs && make html

Code Style

We use ruff for automated code formatting and linting.

Key Commands:

  • ruff check . - Check for style issues

  • ruff check --fix . - Auto-fix issues

  • ruff format . - Format code

Configuration: The project includes a pyproject.toml file with ruff configuration that excludes thirdparty/ directories and ignores physics-specific conventions (E731, E741, E722).

Pre-commit Hooks: Install with pre-commit install to automatically run code quality checks before each commit.

Note: Ruff linting checks are configured as informational only and will not block commits. This allows you to commit your work while still having access to linting feedback. You can address linting issues at your convenience.

Development Workflow

  1. Create a feature branch or fork for your changes

  2. Make your changes following the style guidelines

  3. Test locally before pushing:

    ruff check --fix .
ruff format .
python -m unittest discover tests/
cd docs && make html

  4. Commit your changes: Pre-commit hooks will run automatically but won’t block commits

  5. Optional: Address linting issues when convenient:

    # Check for linting issues
ruff check .

# Auto-fix what can be fixed
ruff check --fix .

# Format code
ruff format .

  6. Push and monitor CI: Check GitHub Actions for automated tests

  7. Submit a pull request