Skip to main content
We welcome contributions to OddsEngine! This guide will help you get started with contributing to our tennis analytics platform.

​
Getting Started

1

Fork the Repository

Fork the OddsEngine repository to your GitHub account.
2

Clone Your Fork

git clone https://github.com/YOUR_USERNAME/OddsEngine.git
cd OddsEngine
3

Set Up Development Environment

Install the required dependencies:Requirements:
  • Python 3.10+
  • Docker and Docker Compose
  • Git
pip install -r requirements.txt

​
Branch Strategy

We follow a structured branching model:
  • main: Production-ready code
  • develop: Integration branch for features
  • feature/*: New features (e.g., feature/probability-calculator)
  • bugfix/*: Bug fixes (e.g., bugfix/api-timeout)
  • hotfix/*: Critical production fixes

​
Creating a Branch

# Create a feature branch from develop
git checkout develop
git pull origin develop
git checkout -b feature/your-feature-name

# For bug fixes
git checkout -b bugfix/issue-description

​
Making Changes

​
Code Standards

  • Follow PEP 8 style guidelines for Python code
  • Write clear, descriptive variable and function names
  • Add docstrings to all functions and classes
  • Keep functions focused and modular
  • Comment complex logic

​
Testing Requirements

Before submitting your contribution: 
pytest tests/
Ensure all tests pass before committing.
  • Test your changes locally with Docker:
docker-compose up --build
  • Verify functionality in the UI
  • Test edge cases and error scenarios
  • Run linting checks
  • Ensure no unnecessary dependencies are added
  • Check for security vulnerabilities

​
Commit Guidelines

​
Commit Message Format

Use clear, descriptive commit messages: 
type(scope): brief description

Detailed explanation if needed
Types:
  • feat: New feature
  • fix: Bug fix
  • docs: Documentation changes
  • style: Code style changes (formatting)
  • refactor: Code refactoring
  • test: Adding or updating tests
  • chore: Maintenance tasks
Examples: 
feat(api): add tennis API integration
fix(calculator): correct probability calculation for combined bets
docs(readme): update installation instructions

​
Pull Request Process

1

Push Your Changes

git add .
git commit -m "feat(scope): description of changes"
git push origin feature/your-feature-name
2

Create Pull Request

  1. Go to the OddsEngine repository on GitHub
  2. Click “New Pull Request”
  3. Select your branch to merge into develop
  4. Fill out the PR template
3

PR Checklist

Complete the checklist in the PR template:
  • Tested changes locally
  • Updated documentation if applicable
  • All tests pass
  • Code follows style guidelines
  • Related issue is linked
4

Code Review

  • Wait for review from team members
  • Address feedback and requested changes
  • Push updates to your branch (PR auto-updates)
5

Merge

Once approved, your PR will be merged by a team member.

​
Reporting Issues

​
Bug Reports

Use our bug report template to report bugs:
  • Provide clear description of the problem
  • Include steps to reproduce
  • Specify expected vs actual results
  • Add screenshots or logs if applicable

​
Feature Requests

Use our feature request template:
  • Describe the functionality clearly
  • Explain the use case and benefits
  • Include acceptance criteria

​
Development Stack

Understanding our technology stack will help you contribute effectively:

Frontend

  • PyQt with QtDesigner
  • Responsive UI design

Backend

  • Python 3.10+
  • Pandas for data analysis
  • Tennis API integration

Database

  • Oracle Database
  • Historical data tracking

DevOps

  • GitHub Actions CI/CD
  • Docker containerization
  • SonarQube for quality

​
Getting Help

If you need assistance:

​
Code of Conduct

  • Be respectful and constructive in discussions
  • Focus on collaboration and learning
  • Follow academic integrity guidelines
  • Respect the SCRUM process and team roles
This project is developed as part of the Fundamentos de Ingeniería de Software course at Pontificia Universidad Javeriana (2026).
Thank you for contributing to OddsEngine!

Build docs developers (and LLMs) love

Get started for freeTalk to us