Contributing

We welcome contributions to scorio! This guide will help you get started.

Development Setup

Fork the repository on GitHub
Clone your fork:

git clone https://github.com/YOUR_USERNAME/scorio.git
cd scorio

Create a virtual environment and install development dependencies:

python -m venv env
source env/bin/activate  # On Windows: env\Scripts\activate
make install

Code Style

Follow PEP 8
Code is formatted using Black
Imports are sorted with isort

Run formatting:

make format

Check formatting:

make format-check

Type Checking

Run mypy for type checking:

make lint

Docstrings

Use Google-style docstrings
Public APIs must be fully documented
Use type hints for all public functions

Example:

def my_function(x: int, y: float) -> str:
    """
    Brief description of the function.

    Args:
        x: Description of parameter x.
        y: Description of parameter y.

    Returns:
        str: Description of return value.

    Examples:
        >>> my_function(1, 2.0)
        'result'
    """
    return str(x + y)

Testing

Write tests for all new functionality:

make test

Tests are located in test/ and use pytest.

Pull Request Process

Create a new branch for your feature:

git checkout -b feature/your-feature-name

Make your changes and commit:

git add .
git commit -m "Add your feature description"

Ensure all tests pass and code is formatted:

make format-check
make lint
make test

Push to your fork:

git push origin feature/your-feature-name

Open a pull request on GitHub

Reporting Issues

Report bugs and request features on our GitHub issues page: https://github.com/mohsenhariri/scorio/issues

Please include:

A clear description of the issue
Steps to reproduce (for bugs)
Expected vs actual behavior
Python version and OS
Minimal code example

License

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