Contributing guidelines#

Introduction#

Thank you for your interest in contributing to PyCFAST! This comprehensive guide will help you get started with development, testing, and understanding our workflow.

Starting#

Follow these steps to set up your development environment:

Fork & Clone

Fork PyCFAST on GitHub

Clone your fork:

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

Set Up Development Environment

uv (Recommended):

Install uv and run:
```
make install-dev
```

Or with pip:

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Generate Local Reference Data

Before running tests, generate local reference data (required for verification and validation tests):
```
cd tests/
python generate_reference_data.py --suite verification  # for verification tests only
python generate_reference_data.py --suite validation    # for validation tests only (slow, 1h+)
python generate_reference_data.py                       # for both (default)
```
Note: Because CFAST uses a Fortran compiler, which can produce small numerical differences between systems and compilers, always generate reference data locally for your tests. You also need to have CFAST installed and accessible in your PATH. You can download it from the NIST CFAST page. Validation data generation can take over an hour depending on your system.
Run Tests & Checks

Ensure everything is set up correctly by running:
```
make allci
```

Development Workflow#

If you want to solve an issue or add a feature, follow these steps:

Create a branch
```
git checkout -b feature/your-feature
```
Write code and tests
- Add features or solve issues in src/pycfast/
- Add/modify tests in tests/units/
Check CI locally (check, format, type, test, coverage)
```
make allci
```

For commit messages, we follow this format:

DEV: development tool or utility
FIX: Bug fix
DOC: Documentation changes
BLD: Dependencies/build system (Makefile, pyproject.toml, ...)
STY: Code formatting
TST: addition or modification of tests
MAINT: maintenance commit (refactoring, typos, etc.)
FEAT: new feature or enhancement
CI: CI/CD workflows
REL: release commit (version bump, changelog update, etc.)
chore: Other maintenance

Commit and push

git add .
git commit -m "FEAT: short description"
git push origin feature/your-feature

Open a Pull Request on PyCFAST GitHub page.

Testing#

We use pytest for testing. Tests are located in the tests/ directory and are categorized into:

Unit tests:

Fast checks for core modules run:
```
pytest tests/units/
```
Or from make file:
```
make test-units
```
Documentation tests:

Ensure example in docstrings are correct and work:
```
pytest --doctest-modules src/pycfast/
```
Or from make file:
```
make test-doctest
```
Verification tests:

Compare PyCFAST with CFAST Verification cases. Ensure you have run generate_reference_data.py --suite verification before running these tests.
```
pytest tests/verification_tests/
```
Or from make file:
```
make test-verif
```
Validation tests:

Parse CFAST Validation input files with parse_cfast_file function and compare the results to the reference data. Ensure you have run generate_reference_data.py --suite validation before running these tests. These tests are slow (1h+) and are not run in the standard test suite.
```
pytest tests/validation_tests/
```
Or from make file:
```
make test-valid
```
Complete test suite:

Run all tests (units + doctest + verification, excluding validation) with:
```
pytest src/pycfast tests/ --ignore=tests/validation_tests
```
Or from make file:
```
make test
```

Code Style#

We use Python 3.10+ with type hints. Code formatting and linting is handled by ruff, and type checking uses mypy. You can run the following commands to check and format your code:

make format # or ruff format .
make check # or ruff check .
make type # or mypy src/

Documentation#

We use Sphinx with MyST for documentation. Use Numpy-style docstrings and add or modify docs in docs/source or as docstrings. The documentation for PyCFAST API reference is auto-generated from docstrings.

To build documentation locally:

With uv:

make install-docs
make doc

Or with pip:

python -m venv .venv
source .venv/bin/activate
pip install -e ".[docs]"
cd docs && sphinx-build -b html source build/html