Contributing to Elote

Thank you for your interest in contributing to Elote! This guide will help you get started with contributing to the project.

Setting Up Your Development Environment

Fork the Repository

Start by forking the Elote repository on GitHub.

Clone Your Fork

git clone https://github.com/your-username/elote.git
cd elote

Set Up Development Environment

# Using Make (recommended)
make install-dev

# Or using pip
pip install -e ".[dev]"

# Or using uv
uv pip install -e ".[dev]"

Set Up Pre-commit Hooks
```
pre-commit install
```

Development Workflow

Create a Branch

Create a branch for your feature or bugfix:

git checkout -b feature/your-feature-name
# or
git checkout -b fix/your-bugfix-name

Make Your Changes

Implement your changes, following the code style guidelines.

Run Tests

Make sure your changes pass all tests:

# Run all tests
make test

# Run tests with coverage
make test-cov

Lint Your Code

Ensure your code follows the project’s style guidelines:

# Check code style
make lint

# Auto-fix some linting issues
make lint-fix

# Format code
make format

Commit Your Changes

Follow the conventional commits format for your commit messages:

git commit -m "feat: add new feature"
# or
git commit -m "fix: resolve issue with X"

Push Your Changes

Push your changes to your fork:
```
git push origin feature/your-feature-name
```
Create a Pull Request

Open a pull request from your fork to the main Elote repository.

Code Style Guidelines

Elote follows these code style guidelines:

Use PEP 8 for Python code style
Use docstrings for all public functions, classes, and methods
Write clear, descriptive variable and function names
Include type hints where appropriate
Keep functions focused on a single responsibility
Write unit tests for new functionality

Adding a New Rating System

To add a new rating system to Elote:

Create a new file in the elote/competitors directory
Implement a new class that inherits from BaseCompetitor
Implement the required methods: - expected_score(competitor) - update_rating(competitor, score)
Add tests for your rating system in the tests directory
Update the documentation to include your new rating system

Here’s a template for a new rating system:

from elote.competitors.base import BaseCompetitor

class NewRatingCompetitor(BaseCompetitor):
    def __init__(self, initial_rating=1500, **kwargs):
        self.rating = initial_rating
        # Initialize other parameters

    def expected_score(self, competitor):
        """
        Calculate the expected score (probability of winning) against another competitor.

        Args:
            competitor: The opponent NewRatingCompetitor

        Returns:
            float: The probability of winning (between 0 and 1)
        """
        # Implement the expected score calculation
        pass

    def update_rating(self, competitor, score):
        """
        Update the rating based on a match result.

        Args:
            competitor: The opponent NewRatingCompetitor
            score: The actual score (1 for win, 0.5 for draw, 0 for loss)
        """
        # Implement the rating update logic
        pass

Documentation

When adding new features or making significant changes, please update the documentation:

Add or update docstrings for all public functions, classes, and methods
Update the relevant RST files in the docs/source directory
If adding a new rating system, create a new RST file in docs/source/rating_systems

Build and check the documentation locally:

make docs
# Open docs/build/html/index.html in your browser

Testing

Elote uses pytest for testing. When adding new features:

Write unit tests for your new code
Ensure all existing tests pass
Aim for high test coverage

# Run tests
make test

# Run tests with coverage
make test-cov

Reporting Issues

If you find a bug or have a feature request:

Check if the issue already exists in the GitHub issues
If not, create a new issue with: - A clear title and description - Steps to reproduce (for bugs) - Expected and actual behavior (for bugs) - Any relevant code snippets or error messages

Pull Request Process

Ensure your code passes all tests and linting checks
Update the documentation if needed
Add an entry to the CHANGELOG.md file
Submit your pull request with a clear description of the changes
Wait for review and address any feedback

Code of Conduct

Please note that Elote has a Code of Conduct. By participating in this project, you agree to abide by its terms.

Thank You!

Your contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contribution you make is greatly appreciated!