Contributing#

We welcome contributions to pyiwfm! This guide explains how to contribute.

Getting Started#

Fork the repository on GitHub

Clone your fork locally:

git clone https://github.com/YOUR_USERNAME/pyiwfm.git
cd pyiwfm

Create a virtual environment and install development dependencies:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e ".[dev]"

Create a branch for your changes:

git checkout -b feature/your-feature-name

Development Workflow#

Running Tests#

# Run all tests
pytest tests/

# Run with coverage
pytest tests/ --cov=pyiwfm --cov-report=html

# Run specific test file
pytest tests/unit/test_mesh.py -v

Code Style#

We use the following tools for code quality:

Ruff for linting and formatting
mypy for type checking

# Format code
ruff format src/ tests/

# Lint code
ruff check src/ tests/

# Type check
mypy src/pyiwfm/

Pre-commit Hooks#

Install pre-commit hooks to automatically check code:

pip install pre-commit
pre-commit install

Writing Tests#

All new features should include tests. Follow these guidelines:

Place unit tests in tests/unit/
Use pytest fixtures for common setup
Name test files test_*.py
Name test functions test_*

Example test:

import pytest
from pyiwfm.core.mesh import Node

def test_node_creation():
    node = Node(id=1, x=100.0, y=200.0)
    assert node.id == 1
    assert node.x == 100.0
    assert node.y == 200.0

Documentation#

Building Documentation#

cd docs
pip install -r requirements.txt
make html

The built documentation will be in docs/_build/html/.

Writing Documentation#

Use NumPy-style docstrings
Include examples in docstrings
Add new modules to the appropriate RST files

Docstring Example#

def example_function(param1: int, param2: str = "default") -> bool:
    """
    Short description of the function.

    Longer description if needed, explaining the function's purpose
    and behavior in more detail.

    Parameters
    ----------
    param1 : int
        Description of param1.
    param2 : str, optional
        Description of param2. Default is "default".

    Returns
    -------
    bool
        Description of return value.

    Raises
    ------
    ValueError
        If param1 is negative.

    Examples
    --------
    >>> example_function(1)
    True
    >>> example_function(1, param2="test")
    True
    """
    pass

Submitting Changes#

Ensure all tests pass
Update documentation if needed
Commit your changes with a descriptive message:
```
git commit -m "Add feature X that does Y"
```

Push to your fork:

git push origin feature/your-feature-name

Open a Pull Request on GitHub

Pull Request Guidelines#

Provide a clear description of the changes
Reference any related issues
Include tests for new features
Update documentation as needed
Ensure CI passes

Code of Conduct#

Please be respectful and constructive in all interactions. We follow the Contributor Covenant code of conduct.

Questions?#

If you have questions, please:

Check existing issues and documentation
Open a new issue with a clear description
Contact the maintainers