feat: Add comprehensive license and repository protection
- Add MIT LICENSE file with proper copyright attribution - Add SECURITY.md with vulnerability reporting guidelines - Add CONTRIBUTING.md with contribution guidelines and standards - Add CODE_OF_CONDUCT.md following Contributor Covenant 2.1 - Add .github/CODEOWNERS for code ownership protection - Add GitHub issue templates (bug report, feature request) - Add pull request template for standardized PRs - Add automated workflows for code quality and security checks - Add dependency review workflow for license compliance This establishes professional standards and protections for the repository.
This commit is contained in:
Claude
parent
3855223bab
commit
16f3810210
10 changed files with 1059 additions and 0 deletions
351
CONTRIBUTING.md
Normal file
351
CONTRIBUTING.md
Normal file
|
|
@ -0,0 +1,351 @@
|
|||
# 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
|
||||
Loading…
Add table
Add a link
Reference in a new issue