CONTRIBUTING.md

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

   git clone https://github.com/yourusername/sam3-mlx.git
   cd sam3-mlx
   

2. Create a branch

   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

   # 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

   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

# 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:

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.