climate_indices Conventions

Generated from monocongo/climate_indices on 2026-08-08, then reviewed against this repository.

Use this skill when changing climate_indices, writing its tests or documentation, or preparing commits.

Project Layout and Module Boundaries

climate_indices is a Python library with a src/ layout. Its production code is the src/climate_indices/ package; tests are direct pytest modules in tests/, with reference data in tests/fixture/.

The package uses responsibility-focused modules:

Keep changes within the established module boundary. Read src/climate_indices/CONTEXT.md before using project domain terminology.

Python Style

Follow the existing package-qualified import style:

from climate_indices import compute
from climate_indices.exceptions import InvalidArgumentError

For an explicitly curated module API, use Python's __all__. Package-level re-exports belong in src/climate_indices/__init__.py.

Public APIs must be typed and documented with Google-style docstrings. Use structlog through climate_indices.logging_config; do not introduce stdlib logging.

Tests and Documentation

• Put pytest tests directly under tests/ as test_*.py.
• Put shared fixtures in tests/conftest.py and stable reference data in tests/fixture/.
• Add or update tests for behavior changes and bug fixes.
• Update documentation for public API, behavior, or workflow changes.

A typical feature touches paths such as:

src/climate_indices/<module>.py
tests/test_<module>.py
tests/fixture/<reference-data>    # when needed
docs/<document>                   # when public behavior changes

Commit Conventions

Use Conventional Commit messages. Common types are:

• feat
• fix
• docs
• test
• refactor
• chore
• ci
• build
• style

Use a scope when it adds useful context, for example:

feat: add rolling-window extreme Z-index sum with wet-side anomaly filter
fix(review): align integrity checks with repository standards
chore(deps): bump actions/checkout from 7.0.0 to 7.0.1

Keep the subject concise, descriptive, and focused on one coherent change.

Validation

For source or test changes, run:

uv run ruff check src/ tests/
uv run ruff format --check src/ tests/
uv run mypy src/
uv run pytest

For packaging, release, or workflow changes, also run:

uv run pytest tests/test_release_integrity.py

Feature Workflow

1. Identify the responsible module and existing tests.
2. Implement the smallest coherent change in src/climate_indices/.
3. Add or update tests/test_*.py coverage and fixtures as needed.
4. Update user-facing documentation when behavior changes.
5. Run the relevant validation commands before review.