GeoGuessrMCP/CONTRIBUTING.md

# Contributing to GeoGuessr MCP Server

Thank you for your interest in contributing to the GeoGuessr MCP Server! This document provides guidelines and instructions for contributing.

## Table of Contents

- [Code of Conduct](#code-of-conduct)
- [Getting Started](#getting-started)
- [Development Setup](#development-setup)
- [How to Contribute](#how-to-contribute)
- [Coding Standards](#coding-standards)
- [Testing](#testing)
- [Pull Request Process](#pull-request-process)
- [License](#license)

## Code of Conduct

### Our Standards

- **Be Respectful**: Treat everyone with respect and professionalism
- **Be Collaborative**: Work together constructively
- **Be Patient**: Help others learn and grow
- **Be Inclusive**: Welcome diverse perspectives and backgrounds

### Unacceptable Behavior

- Harassment, discrimination, or offensive comments
- Personal attacks or trolling
- Publishing others' private information
- Any conduct that would be inappropriate in a professional setting

## Getting Started

1. **Fork the repository** on GitHub
2. **Clone your fork** locally:
   ```bash
   git clone https://github.com/YOUR_USERNAME/GeoGuessrMCP.git
   cd GeoGuessrMCP
   ```
3. **Add upstream remote**:
   ```bash
   git remote add upstream https://github.com/NyxiumYuuki/GeoGuessrMCP.git
   ```

## Development Setup

### Prerequisites

- Python 3.13 or higher
- Docker and Docker Compose (for containerized development)
- Git

### Installation

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

# Install dependencies
pip install -e ".[dev]"

# Set up pre-commit hooks (optional but recommended)
pre-commit install
```

### Environment Configuration

Create a `.env` file with your configuration:

```env
GEOGUESSR_NCFA_COOKIE=your_cookie_here
MONITORING_ENABLED=true
MONITORING_INTERVAL_HOURS=24
LOG_LEVEL=DEBUG
```

## How to Contribute

### Reporting Bugs

Before creating a bug report:
1. **Check existing issues** to avoid duplicates
2. **Use the latest version** to verify the bug still exists
3. **Collect information**: version, OS, steps to reproduce

Create a detailed bug report including:
- Clear, descriptive title
- Steps to reproduce
- Expected vs. actual behavior
- Screenshots or logs (if applicable)
- Environment details

### Suggesting Enhancements

Enhancement suggestions are welcome! Include:
- Clear description of the proposed feature
- Rationale and use cases
- Examples of how it would work
- Any potential drawbacks or alternatives

### Contributing Code

1. **Find or create an issue** for the change you want to make
2. **Create a branch** from main:
   ```bash
   git checkout -b feature/your-feature-name
   # or
   git checkout -b fix/issue-number-description
   ```
3. **Make your changes** following our coding standards
4. **Write tests** for your changes
5. **Run tests** to ensure nothing breaks
6. **Commit your changes** with clear messages
7. **Push to your fork** and create a pull request

## Coding Standards

### Python Style

We follow PEP 8 with some modifications:

- **Line length**: 100 characters (Black formatter)
- **Formatting**: Use Black for automatic formatting
- **Linting**: Use Ruff for code quality checks
- **Type hints**: Required for all functions (MyPy strict mode)

### Code Quality Tools

Run before committing:

```bash
# Format code
black src/ tests/

# Lint code
ruff check src/ tests/

# Type checking
mypy src/

# Run all checks
black src/ tests/ && ruff check src/ tests/ && mypy src/
```

### Best Practices

1. **Keep functions focused**: One responsibility per function
2. **Use type hints**: All parameters and return values
3. **Write docstrings**: For all public functions and classes
4. **Avoid over-engineering**: Simple solutions are preferred
5. **Handle errors gracefully**: Use proper exception handling
6. **Log appropriately**: Use logging module, not print()

### Docstring Format

Use Google-style docstrings:

```python
def function_name(param1: str, param2: int) -> bool:
    """Brief description of function.

    Longer description if needed.

    Args:
        param1: Description of param1
        param2: Description of param2

    Returns:
        Description of return value

    Raises:
        ValueError: When something goes wrong
    """
    pass
```

## Testing

### Running Tests

```bash
# Run all tests
pytest

# Run with coverage
pytest --cov=src/geoguessr_mcp tests/

# Run specific test file
pytest tests/unit/test_specific.py

# Run tests matching a pattern
pytest -k "test_auth"

# Run with verbose output
pytest -v
```

### Writing Tests

- **Unit tests**: Test individual components in isolation
- **Integration tests**: Test component interactions
- **Mock external calls**: Use `respx` for HTTP mocking
- **Use fixtures**: Defined in `tests/conftest.py`
- **Test coverage**: Aim for 80%+ coverage on new code

Example test:

```python
import pytest
from geoguessr_mcp.services.profile import ProfileService

async def test_get_profile_success(mock_auth_session):
    """Test successful profile retrieval."""
    service = ProfileService(mock_auth_session)
    profile = await service.get_profile("user123")

    assert profile is not None
    assert profile.id == "user123"
```

## Pull Request Process

### Before Submitting

- [ ] Code follows style guidelines
- [ ] All tests pass
- [ ] New tests added for new features
- [ ] Documentation updated (if applicable)
- [ ] Commits are clear and atomic
- [ ] No merge conflicts with main branch

### PR Guidelines

1. **Title**: Clear, concise description
2. **Description**: Explain what and why, not how
3. **Link issues**: Reference related issues
4. **Screenshots**: Include for UI changes
5. **Breaking changes**: Clearly document

### PR Template

```markdown
## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Related Issues
Fixes #123

## Testing
Describe testing performed

## Checklist
- [ ] Tests pass
- [ ] Code follows style guide
- [ ] Documentation updated
```

### Review Process

1. **Automated checks**: CI/CD must pass
2. **Code review**: At least one approval required
3. **Owner approval**: Code owners must approve changes to owned files
4. **Feedback**: Address all review comments
5. **Merge**: Squash and merge (typically)

## Commit Message Guidelines

Follow conventional commits format:

```
<type>(<scope>): <subject>

<body>

<footer>
```

**Types**:
- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation changes
- `style`: Formatting, no code change
- `refactor`: Code restructuring
- `test`: Adding or updating tests
- `chore`: Maintenance tasks

**Examples**:
```
feat(monitoring): add endpoint health checks

Implement periodic health checks for all monitored endpoints.
Includes retry logic and failure notifications.

Closes #42
```

```
fix(auth): handle expired cookie gracefully

Previously, expired cookies caused unhandled exceptions.
Now we catch and re-authenticate automatically.

Fixes #58
```

## Documentation

### When to Update Documentation

- Adding new features or tools
- Changing existing functionality
- Adding configuration options
- Updating dependencies or requirements

### Documentation Locations

- **README.md**: Overview, quick start, basic usage
- **CLAUDE.md**: Developer guide for AI assistants
- **Code comments**: Complex logic explanation
- **Docstrings**: All public APIs

## License

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

## Getting Help

- **Questions**: Open a GitHub Discussion
- **Bugs**: Create an issue
- **Security**: Email yuki.vachot@datasingularity.fr

## Recognition

Contributors will be recognized in:
- GitHub contributors list
- Release notes (for significant contributions)
- Special mentions for major features

Thank you for contributing to GeoGuessr MCP Server! 🎉

---

**Maintainer**: Yûki VACHOT (@NyxiumYuuki)
**Last Updated**: 2025-11-29