# Contributing to CAVORA

First off, thank you for considering contributing to CAVORA! It's people like you that make CAVORA such a great tool for the speleological community.

## Code of Conduct

This project and everyone participating in it is governed by our [Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code.

## How Can I Contribute?

### Reporting Bugs

Before creating bug reports, please check the issue list as you might find out that you don't need to create one. When you are creating a bug report, please include as many details as possible:

- **Use a clear and descriptive title**
- **Describe the exact steps to reproduce the problem**
- **Provide specific examples** (commands, code snippets)
- **Describe the behavior you observed and why it's a problem**
- **Include logs and error messages**
- **Specify your environment** (OS, Python version, CAVORA version)

### Suggesting Enhancements

Enhancement suggestions are tracked as GitHub issues. When creating an enhancement suggestion, please include:

- **A clear and descriptive title**
- **A detailed description of the proposed functionality**
- **Explain why this enhancement would be useful**
- **List any alternative solutions you've considered**
- **Include examples of how the feature would be used**

### Adding Field Data

We welcome field data contributions from cave systems worldwide. Please ensure:

1. Data follows the standard CAVORA format (see `data/README.md`)
2. Include metadata (location, dates, survey methods)
3. Anonymize sensitive location data if required
4. Include validation information (closure errors, etc.)

### Improving Documentation

Documentation improvements are always welcome. This includes:

- Fixing typos or clarifying explanations
- Adding examples and tutorials
- Translating documentation
- Updating docstrings

## Pull Request Process

1. **Fork the repository** and create your branch from `main`
2. **If you've added code, add tests** that cover your changes
3. **Ensure the test suite passes** by running `pytest`
4. **Update documentation** if necessary
5. **Follow the coding style** (we use Black)
6. **Write a clear PR description** explaining your changes

### PR Requirements

- All tests must pass
- Code coverage should not decrease
- Code must be formatted with Black
- Docstrings must be updated for new functions
- CHANGELOG.md must be updated for significant changes

## Development Setup

```bash
# Clone your fork
git clone https://gitlab.com/your-username/cavova.git
cd cavova

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

# Install development dependencies
pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install

# Run tests
pytest tests/

# Check code style
black --check cavora/
flake8 cavora/
mypy cavora/
```

Coding Guidelines

Python Style Guide

· Follow PEP 8
· Use Black for formatting
· Maximum line length: 100 characters
· Use type hints for all functions
· Write docstrings in Google format

Example Function

```python
def calculate_stability(v: float, l: float, f: float) -> Dict[str, float]:
    """
    Calculate stability score from VLF parameters.
    
    Args:
        v: Vertical passage dimension (m)
        l: Lateral conduit dimension (m)
        f: Flowstone thickness (mm)
        
    Returns:
        Dictionary containing stability score and components
        
    Raises:
        ValueError: If parameters are outside valid ranges
        
    Example:
        >>> calculate_stability(2.5, 3.0, 0.08)
        {'score': 95.0, 'v_contrib': 0.4, 'l_contrib': 0.35, 'f_contrib': 0.25}
    """
    # Implementation here
    pass
```

Testing Guidelines

· Write unit tests for all new functionality
· Aim for >80% code coverage
· Use descriptive test names
· Mock external dependencies

```python
def test_stability_calculation_with_valid_inputs():
    """Test stability calculation with typical values."""
    result = calculate_stability(2.5, 3.0, 0.08)
    assert result['score'] > 90
    assert 0 <= result['v_contrib'] <= 1
```

Branch Naming Convention

· feature/ - New features
· bugfix/ - Bug fixes
· docs/ - Documentation updates
· test/ - Test improvements
· refactor/ - Code refactoring
· data/ - Data contributions

Example: feature/cdz-detection-algorithm

Commit Message Guidelines

Follow Conventional Commits:

```
<type>[optional scope]: <description>

[optional body]

[optional footer(s)]
```

Types:

· feat: New feature
· fix: Bug fix
· docs: Documentation
· style: Code style (formatting, etc.)
· refactor: Code refactoring
· test: Adding/updating tests
· chore: Maintenance tasks

Examples:

```
feat(cdz): add real-time CDZ proximity calculation
fix(hydrology): correct discharge calculation for flood events
docs: update API reference for stability module
```

Release Process

1. Update version in cavora/__init__.py
2. Update CHANGELOG.md
3. Create release branch release/vX.Y.Z
4. Run full test suite
5. Create merge request to main
6. Tag release after merge

Getting Help

· Documentation: Read the docs
· Issues: GitLab Issues
· Discussions: GitLab Discussions
· Email: dev@cavora.org

Recognition

Contributors will be acknowledged in:

· AUTHORS.md file
· Release notes
· Academic publications (with consent)

Thank you for contributing to CAVORA! 🕳️
