# Contributing to SAM3 MLX

Thank you for considering contributing to SAM3 MLX! This document provides guidelines for contributing to the project.

## Code of Conduct

Be respectful and professional. We're all here to build great software together.

## How to Contribute

### Reporting Bugs

If you find a bug, please open an issue with:
- Clear description of the problem
- Steps to reproduce
- Expected vs actual behavior
- Your environment (Mac model, macOS version, MLX version)
- Error messages and stack traces

### Suggesting Features

Feature requests are welcome! Please include:
- Clear use case
- Why this feature would be useful
- How it might work

### Pull Requests

1. **Fork the repository**
   ```bash
   git clone https://github.com/yourusername/sam3-mlx.git
   cd sam3-mlx
   ```

2. **Create a branch**
   ```bash
   git checkout -b feature/your-feature-name
   ```

3. **Make your changes**
   - Write clear, documented code
   - Follow the existing code style
   - Add tests for new functionality
   - Update documentation as needed

4. **Test your changes**
   ```bash
   # Run tests
   python tests/test_models.py

   # Run benchmarks
   python tests/benchmark.py

   # Check code style
   black sam3_mlx/
   ruff check sam3_mlx/
   ```

5. **Commit and push**
   ```bash
   git add .
   git commit -m "Add feature: your feature description"
   git push origin feature/your-feature-name
   ```

6. **Open a Pull Request**
   - Describe what you changed and why
   - Link any related issues
   - Wait for review

## Development Setup

```bash
# Clone the repository
git clone https://github.com/yourusername/sam3-mlx.git
cd sam3-mlx

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

# Run tests
python tests/test_models.py
```

## Code Style

- **Python**: Follow PEP 8
- **Line length**: 100 characters
- **Formatting**: Use `black` for auto-formatting
- **Linting**: Use `ruff` for linting
- **Type hints**: Add type hints for function signatures

Example:
```python
def process_image(image: mx.array, size: int = 1024) -> mx.array:
    """
    Process image for SAM3 input

    Args:
        image: Input image array
        size: Target size

    Returns:
        Processed image
    """
    # Implementation here
    return processed_image
```

## Testing

- Add tests for all new features
- Maintain or improve code coverage
- Test on actual Apple Silicon hardware when possible
- Verify performance benchmarks don't regress

## Documentation

- Document all public functions and classes
- Update README.md for major changes
- Add examples for new features
- Keep docstrings up to date

## Performance

- Profile new code for performance
- Avoid unnecessary copies with MLX arrays
- Use MLX operations instead of numpy when possible
- Benchmark performance-critical changes

## Commit Messages

Write clear commit messages:
- Use present tense ("Add feature" not "Added feature")
- Keep first line under 72 characters
- Add detailed description if needed

Good examples:
```
Add RoPE attention implementation

Implements Rotary Position Embeddings for spatial awareness
in the vision transformer.
```

```
Fix memory leak in mask decoder

The transformer was not releasing intermediate tensors,
causing memory to grow with each inference.
```

## Release Process

Maintainers will:
1. Update version in `pyproject.toml`
2. Update CHANGELOG.md
3. Create a git tag
4. Publish to PyPI

## Questions?

Open an issue or start a discussion!

## License

By contributing, you agree that your contributions will be licensed under the MIT License.