# Contributing to TRX-Python

We welcome contributions from the community! This guide will help you get started
with contributing to the TRX-Python project.

## Ways to Contribute

There are many ways to contribute to TRX-Python:

- **Report bugs**: If you find a bug, please open an issue on GitHub
- **Suggest features**: Have an idea? Open an issue to discuss it
- **Fix bugs**: Look for issues labeled "good first issue" or "help wanted"
- **Write documentation**: Help improve our docs or add examples
- **Write tests**: Increase test coverage
- **Code review**: Review pull requests from other contributors

## Getting Started

1. **Fork the repository** on GitHub
2. **Clone your fork**:

   ```bash
   git clone https://github.com/YOUR_USERNAME/trx-python.git
   cd trx-python
   ```

3. **Set up development environment**:

   ```bash
   pip install -e ".[all]"
   spin setup
   ```

   The `spin setup` command fetches version tags from upstream, which is
   required for correct version detection.

4. **Create a branch** for your changes:

   ```bash
   git checkout -b my-feature-branch
   ```

## Making Changes

### Development Workflow

We use [spin](https://github.com/scientific-python/spin) for development workflow:

```bash
spin install    # Install in editable mode
spin test       # Run all tests
spin lint       # Run linting (ruff)
spin docs       # Build documentation
```

### Before Submitting

1. **Run tests** to ensure your changes don't break existing functionality:

   ```bash
   spin test
   ```

2. **Run linting** to ensure code style compliance:

   ```bash
   spin lint
   ```

   You can auto-fix many issues with:

   ```bash
   spin lint --fix
   ```

3. **Format your code** using ruff:

   ```bash
   ruff format .
   ```

4. **Write tests** for any new functionality

5. **Update documentation** if needed

## Submitting a Pull Request

1. **Push your changes** to your fork:

   ```bash
   git push origin my-feature-branch
   ```

2. **Open a Pull Request** on GitHub against the `master` branch

3. **Describe your changes** in the PR description:

   - What does this PR do?
   - Why is this change needed?
   - How was it tested?

4. **Wait for CI checks** to pass

5. **Address review feedback** if requested

## Code Style

We follow these conventions:

- **PEP 8** style guide
- **Line length**: 88 characters maximum
- **Docstrings**: NumPy style format
- **Type hints**: Encouraged but not required

Example docstring:

```python
def my_function(param1, param2):
    """Short description of the function.

    Parameters
    ----------
    param1 : int
        Description of param1.
    param2 : str
        Description of param2.

    Returns
    -------
    result : bool
        Description of return value.

    Examples
    --------
    >>> my_function(1, "test")
    True
    """
    pass
```

We use [ruff](https://docs.astral.sh/ruff/) for linting and formatting.
Configuration is in `ruff.toml`.

## Testing

Tests are located in `trx/tests/`. We use pytest for testing.

### Running Tests

```bash
# Run all tests
spin test

# Run tests matching a pattern
spin test -m memmap

# Run with verbose output
spin test -v

# Run a specific test file
pytest trx/tests/test_memmap.py
```

### Writing Tests

- Place tests in `trx/tests/`
- Name test files `test_*.py`
- Name test functions `test_*`
- Use pytest fixtures for common setup

## Documentation

Documentation is built with Sphinx and hosted on GitHub Pages.

### Building Docs

```bash
spin docs              # Build documentation
spin docs --clean      # Clean build
spin docs --open       # Build and open in browser
```

### Writing Documentation

- Documentation source is in `docs/source/`
- Use MyST Markdown format
- API documentation is auto-generated from docstrings

## Getting Help

- **GitHub Issues**: For bugs and feature requests
- **GitHub Discussions**: For questions and discussions

Thank you for contributing to TRX-Python!