Contributing¶

Contributing to AquaCal¶

Thank you for your interest in contributing to AquaCal. This guide will help you get started with development.

Development Setup¶

Clone the repository:

git clone https://github.com/tlancaster6/AquaCal.git
cd AquaCal

Create and activate a virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

Install the package with development dependencies:
```
pip install -e ".[dev]"
```
Run tests to verify your setup:
```
python -m pytest tests/
```

Code Style¶

Formatter: Ruff (run ruff format src/ tests/ before committing)
Linter: Ruff (run ruff check src/ tests/ to check for issues)
Docstrings: Google style
Type hints: Use numpy.typing.NDArray with shape information in docstrings
Imports ordering:
1. Standard library imports
2. Third-party imports (numpy, scipy, opencv, etc.)
3. Local imports (from aquacal)
Separate each group with a blank line.

This project uses git hooks via pre-commit to catch issues early:

On commit: ruff lint/format, trailing whitespace, end-of-file fixer, YAML check, large file check, and secret detection (detect-secrets)
On push: full ruff lint/format check across all files, fast test suite (pytest -m "not slow"), and secret detection

Install both hooks after cloning:

pre-commit install
pre-commit install --hook-type pre-push

If you modify documentation, you can verify the build locally before pushing, or let the GitHub CI catch issues after you push:

sphinx-build -W --keep-going -b html docs docs/_build/html

Running Tests¶

Run all tests:

python -m pytest tests/

Skip slow optimization tests:

python -m pytest tests/ -m "not slow"

Run a single test file:

python -m pytest tests/unit/test_camera.py -v

Submitting Changes¶

Fork the repository
Create a feature branch (git checkout -b feature/your-feature)
Make your changes and add tests
Ensure all tests pass
Format and lint your code with ruff (ruff format src/ tests/ && ruff check src/ tests/)
Commit your changes with a clear message (see Commit Messages below)
Push to your fork and submit a pull request

Commit Messages¶

This project uses Conventional Commits for automated versioning. Format your commit messages as:

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

[optional body]

Types:

feat: A new feature (triggers minor version bump, e.g., 1.0.0 → 1.1.0)
fix: A bug fix (triggers patch version bump, e.g., 1.0.0 → 1.0.1)
docs: Documentation changes only
test: Adding or updating tests
refactor: Code changes that neither fix bugs nor add features
chore: Maintenance tasks (dependencies, tooling, etc.)

Scope (optional): The area of the codebase affected, e.g., calibration, cli, core

Examples:

feat(calibration): add support for tilted water surfaces
fix(projection): correct Newton-Raphson convergence criterion
docs: update README installation instructions
test(synthetic): add test for multi-camera pose graph

Deprecation Policy¶

When deprecating functionality in AquaCal:

Add a deprecation warning using warnings.warn() with DeprecationWarning:

import warnings

def old_function():
    warnings.warn(
        "old_function() is deprecated as of version 1.2.0 and will be removed in version 1.4.0. "
        "Use new_function() instead.",
        DeprecationWarning,
        stacklevel=2
    )
    # existing implementation

Maintain for at least 2 minor versions before removal.

Document the replacement in the function’s docstring:

def old_function():
    """Original description.

    .. deprecated:: 1.2.0
        Use :func:`new_function` instead. Will be removed in version 1.4.0.
    """

Always include stacklevel=2 in warnings to show the caller’s location, not the warning itself.