entropice/CONTRIBUTING.md

# Contributing to Entropice

Thank you for your interest in contributing to Entropice! This document provides guidelines for contributing to the project.

## Getting Started

### Prerequisites

- CUDA 12 compatible GPU (for full functionality)
- [Pixi package manager](https://pixi.sh/)

### Setup

```bash
pixi install
```

This will set up the complete environment including Python, RAPIDS, PyTorch, and all geospatial dependencies.

## Development Workflow

> Read in the [Architecture Guide](ARCHITECTURE.md) about the code organisatoin and key modules

**Important**: Always use `pixi run` to execute Python commands and scripts to ensure you're using the correct environment with all dependencies:

```bash
pixi run python script.py
pixi run python -c "import entropice"
```

### Python Style and Formatting

- Follow PEP 8 conventions
- Use type hints for function signatures
- Prefer google-style docstrings for public functions
- Keep functions focused and modular

`ty` and `ruff` are used for typing, linting and formatting.
Ensure to check for any warnings from both of these:

```sh
pixi run ty check # For type checks
pixi run ruff check # For linting
pixi run ruff format # For formatting
```

Single files can be specified by just adding them to the command, e.g. `pixi run ty check src/entropice/dashboard/app.py`

## Testing

Run tests for specific modules:

```bash
pixi run pytest
```

When adding features, include tests that verify:

- Correct handling of geospatial coordinates and projections
- Proper aggregation to grid cells
- Data integrity through pipeline stages

## Submitting Changes

### Pull Request Process

1. **Branch**: Create a feature branch from `main`
2. **Commit**: Write clear, descriptive commit messages
3. **Test**: Verify your changes don't break existing functionality
4. **Document**: Update relevant docstrings and documentation
5. **PR**: Submit a pull request with a clear description of changes

### Commit Messages

- Use present tense: "Add feature" not "Added feature"
- Keep first line under 72 characters

### Notebooks

- Notebooks in `notebooks/` are for exploration and validation, they are not commited to git
- Keep production code in `src/entropice/`

## Dashboard Development

Run the dashboard locally:

```bash
pixi run dashboard
```

Dashboard code is in `src/entropice/dashboard/` with modular pages and plotting utilities.

## Questions?

For questions about the architecture, see `ARCHITECTURE.md`. For scientific background, see `README.md`.