# Contributing to EDref

Thank you for your interest in contributing to EDref! This document provides guidelines and instructions for contributing.

## Getting Started

### Prerequisites

- Python 3.10 or higher
- Git

### Development Setup

1. Clone the repository:
   ```bash
   git clone https://gitlab.com/edref/edref.git
   cd edref
   ```

2. Create a virtual environment:
   ```bash
   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   ```

3. Install in development mode:
   ```bash
   pip install -e ".[dev]"
   ```

4. Verify the installation:
   ```bash
   pytest tests/ -v
   ```

## Development Workflow

### Code Style

We use [Ruff](https://docs.astral.sh/ruff/) for linting and formatting:

```bash
# Check for issues
ruff check src/

# Auto-fix issues
ruff check --fix src/

# Format code
ruff format src/
```

### Type Hints

All new code should include type hints. We use mypy for type checking:

```bash
mypy src/edref
```

### Running Tests

```bash
# Run all tests
pytest tests/ -v

# Run with coverage
pytest tests/ -v --cov=src/edref --cov-report=term-missing

# Run specific test file
pytest tests/test_structure_factors.py -v
```

### Documentation

- Update `manual.md` when adding new features or changing APIs
- Update `CLAUDE.md` when adding critical rules or patterns
- Use docstrings following NumPy style for all public functions

## Making Changes

### Branch Naming

- `feature/description` - New features
- `fix/description` - Bug fixes
- `docs/description` - Documentation changes
- `refactor/description` - Code refactoring

### Commit Messages

Write clear, descriptive commit messages:

```
Add robust biweight scaling for ED data

- Implement Tukey biweight M-estimator
- Add benchmark tests against SHELXL
- Update documentation with usage examples
```

### Pull/Merge Requests

1. Create a new branch from `main`
2. Make your changes
3. Run tests and linting
4. Push your branch
5. Open a Merge Request on GitLab
6. Fill out the MR template with:
   - Description of changes
   - Related issues
   - Testing performed
   - Documentation updates

## Code Organization

```
src/edref/
├── core/           # Crystallographic fundamentals
├── io/             # File I/O (SHELXL formats)
├── refinement/     # Least-squares refinement
├── analysis/       # Data processing
└── cli/            # Command-line interface
```

### Adding New Features

1. **Core crystallography** (`core/`): Unit cell, symmetry, scattering
2. **File I/O** (`io/`): Parsers for crystallographic formats
3. **Refinement** (`refinement/`): Least-squares algorithms, parameters
4. **Analysis** (`analysis/`): Merging, scaling, statistics
5. **CLI** (`cli/`): Command-line tools

### Module Guidelines

- Keep modules focused on single responsibilities
- Export public API in `__init__.py`
- Use type hints for all function signatures
- Include docstrings with examples

## Testing Guidelines

### Test Structure

- Place tests in `tests/` mirroring `src/edref/` structure
- Name test files `test_<module>.py`
- Name test functions `test_<function>_<scenario>`

### Test Data

- Use files in `example_data_do_not_modify/` for validation
- Do NOT modify these files
- Create temporary files for destructive tests

### What to Test

- Public API functions
- Edge cases (empty input, extreme values)
- Error conditions
- SHELXL compatibility (compare outputs)

## Reporting Issues

### Bug Reports

Include:
- EDref version (`pip show edref`)
- Python version
- Operating system
- Minimal reproducible example
- Expected vs actual behavior
- Error messages/tracebacks

### Feature Requests

Include:
- Use case description
- Proposed API/interface
- Examples of similar features in other software

## Code of Conduct

- Be respectful and inclusive
- Focus on constructive feedback
- Help others learn and improve

## Questions?

- Open an issue on GitLab
- Check existing documentation in `manual.md`

Thank you for contributing to EDref!
