Skip to content

Contributing to ICE Locator MCP Server

Thank you for your interest in contributing! This guide outlines how to contribute effectively.

Quick Start

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature/your-feature
  3. Make your changes
  4. Add tests and documentation
  5. Submit a pull request

Development Setup

# Clone your fork
git clone https://github.com/yourusername/ice-locator-mcp.git
cd ice-locator-mcp

# 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

Code Standards

Python Code Style

  • Follow PEP 8
  • Use type hints
  • Maximum line length: 88 characters
  • Use Black for formatting
  • Use Ruff for linting
# Format code
black src/ tests/

# Lint code
ruff check src/ tests/

# Type checking
mypy src/ice_locator_mcp/

Testing Requirements

  • Write tests for all new features
  • Maintain >90% code coverage
  • Use pytest for testing
  • Mock external dependencies
# Run tests
pytest

# Run with coverage
pytest --cov=ice_locator_mcp --cov-report=html

Contribution Types

Bug Reports

When reporting bugs, include: - Python version - Package version - Minimal reproduction code - Expected vs actual behavior - Error messages and stack traces

Feature Requests

For new features: - Describe the use case - Explain why it's needed - Provide implementation ideas - Consider backward compatibility

Code Contributions

  • Follow the development workflow
  • Write comprehensive tests
  • Update documentation
  • Follow commit message conventions

Commit Message Format

Use conventional commits:

type(scope): description

[optional body]

[optional footer]

Types: - feat: New feature - fix: Bug fix - docs: Documentation changes - style: Code style changes - refactor: Code refactoring - test: Test changes - chore: Build/config changes

Examples: 

feat(search): add fuzzy matching for names
fix(proxy): handle connection timeouts properly
docs(api): update search tool examples

Pull Request Process

  1. Branch Naming: Use descriptive names
  2. feature/fuzzy-search
  3. fix/proxy-timeout

  4. docs/api-examples

  5. PR Description: Include

  6. What changes were made
  7. Why they were needed
  8. How to test the changes

  9. Related issues

  10. Review Process:

  11. All PRs require review
  12. Address feedback promptly
  13. Keep PRs focused and small
  14. Squash commits before merging

Areas for Contribution

High Priority

  • [ ] Improved CAPTCHA solving
  • [ ] Additional fuzzy matching algorithms
  • [ ] Performance optimizations
  • [ ] More comprehensive tests

Documentation

  • [ ] Tutorial videos
  • [ ] Use case examples
  • [ ] Translation to Spanish
  • [ ] API reference improvements

Tools and Infrastructure

  • [ ] Docker improvements
  • [ ] CI/CD enhancements
  • [ ] Release automation
  • [ ] Monitoring tools

Security

For security vulnerabilities: - DO NOT open public issues - Email: security@example.com - Include detailed reproduction steps - Allow time for responsible disclosure

Code License

  • All contributions are licensed under MIT
  • By contributing, you agree to this license
  • Do not include copyrighted code

Use Case Compliance

  • Ensure contributions support legitimate uses
  • Consider privacy and ethical implications
  • Follow applicable laws and regulations

Community Guidelines

Code of Conduct

  • Be respectful and inclusive
  • Focus on constructive feedback
  • Help newcomers learn
  • Follow the Code of Conduct

Communication

  • Use GitHub issues for bugs/features
  • Use GitHub discussions for questions
  • Be patient with responses
  • Provide helpful context

Testing Guidelines

Unit Tests

# Test structure
def test_feature_name():
    # Arrange
    setup_data = create_test_data()

    # Act
    result = function_under_test(setup_data)

    # Assert
    assert result == expected_value

Integration Tests

  • Test complete workflows
  • Use mock external services
  • Test error conditions
  • Verify caching behavior

Performance Tests

  • Benchmark critical paths
  • Test under load
  • Monitor memory usage
  • Test rate limiting

Documentation Standards

Code Documentation

  • Use docstrings for all public functions
  • Include parameter types and descriptions
  • Provide usage examples
  • Document exceptions
def search_by_name(first_name: str, last_name: str) -> SearchResult:
    """Search for detainees by name.

    Args:
        first_name: First name to search for
        last_name: Last name to search for

    Returns:
        SearchResult containing found detainees

    Raises:
        ValidationError: If names are invalid
        RateLimitError: If rate limit exceeded

    Example:
        >>> result = search_by_name("John", "Doe")
        >>> print(result.total_results)
        1
    """

User Documentation

  • Write for non-technical users
  • Include practical examples
  • Provide troubleshooting steps
  • Keep up-to-date with code changes

Release Process

Version Numbering

  • Follow semantic versioning (MAJOR.MINOR.PATCH)
  • Breaking changes increment MAJOR
  • New features increment MINOR
  • Bug fixes increment PATCH

Release Checklist

  • [ ] Update version numbers
  • [ ] Update CHANGELOG.md
  • [ ] Run full test suite
  • [ ] Update documentation
  • [ ] Create release notes
  • [ ] Tag release
  • [ ] Deploy to PyPI

Getting Help

For Contributors

  • Check existing issues and PRs
  • Read the documentation thoroughly
  • Ask questions in GitHub discussions
  • Join development meetings (if scheduled)

For Maintainers

  • Review PRs promptly
  • Provide constructive feedback
  • Help with complex technical decisions
  • Maintain project roadmap

Recognition

Contributors are recognized in: - CONTRIBUTORS.md file - Release notes - GitHub repository insights - Annual contribution summaries

Thank you for contributing to ICE Locator MCP Server!