Contributing

The contribution guide is maintained at the repository root and reproduced below.

Contributing to VANE

Thank you for your interest in VANE. This document describes how to set up a development environment and the workflow, quality bar, and review process used in this project.

VANE is developed at the SMI Lab, Inha University. Questions can be directed to Jae Hoon Seo (jaehoon.seo@inha.ac.kr).

Development environment

VANE uses a src-layout package and targets Python 3.10–3.12. A conda environment is recommended for the scientific stack.

conda create -n vane python=3.11 -y
conda activate vane
pip install -e ".[dev]"
pre-commit install
pre-commit install --hook-type commit-msg

The optional extras are .[ml] (PyTorch-based components) and .[docs] (the documentation toolchain).

Branch and commit conventions

  • main is protected and holds tagged releases only.

  • develop is the integration branch; it must stay green.

  • Work happens on short-lived branches off develop: feat/<name>, fix/<name>, chore/<name>, docs/<name>, test/<name>.

  • Never commit directly to main or develop; open a pull request instead.

Commit messages follow Conventional Commits:

<type>(<scope>): <short description>

type is one of feat, fix, chore, test, docs, refactor, perf, ci; scope is a module name (io, modal, ai, campbell, viz, sysid, config).

Quality bar

All of the following must pass before a pull request is merged:

  • ruff check src/ tests/ and ruff format --check src/ tests/ — zero warnings.

  • mypy src/ under --strict — zero errors.

  • pytest — all tests pass; coverage must stay at or above 85% (70% for viz/).

  • Every public function and class carries a NumPy-style docstring.

  • Library code uses the logging module, never print.

Pre-commit hooks enforce the lint, format, and type checks locally. Run the full test suite with:

pytest                # full suite with coverage gate
pytest -n auto        # parallel
pytest tests/test_modal/ -v

Adding a module or feature

  1. Place code in the appropriate subpackage under src/vane/.

  2. Add a matching test module under tests/ with at least one passing test.

  3. For numerically meaningful behaviour, add a validation entry to docs/validation.md against an analytical or reference solution.

  4. Update CHANGELOG.md under the [Unreleased] heading.

Pull request process

  1. Open the pull request against develop.

  2. Wait for continuous integration to finish: lint, type check, tests on Python 3.10–3.12, and the automated review summary.

  3. Address any failures on the feature branch and push again.

  4. A pull request is merged only when every check is green.

By contributing, you agree that your contributions are licensed under the project’s Apache-2.0 license, and that you will uphold the Code of Conduct.