95 lines
2.5 KiB
Markdown
95 lines
2.5 KiB
Markdown
# 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`.
|