CONTRIBUTING.md

Contributing to Checkora ♟️

Thank you for considering contributing to Checkora — a chess engine powered by minimax with alpha-beta pruning, served via Django. We welcome contributions from the community, especially GSSoC contributors!

---

🗺️ Table of Contents

• Contributing to Checkora ♟️
  • 🗺️ Table of Contents
  • 🏅 GSSoC Contributors - Start Here
  • 🚀 Getting Started
  • 🛠️ Development Setup
    • Prerequisites
    • Installation
    • Running Tests
    • Checking for Missing Migrations
    • Linting (must pass before submitting a PR)
  • ⚙️ CI/CD Pipeline
  • 🌿 Branch Naming Convention
  • 📝 Commit Message Format
    • Rules
    • Examples
  • 🔀 Pull Request Guidelines
    • Keeping Your Fork Up to Date
  • 🎨 Code Style
  • 🐛 Reporting Issues
  • 📋 Code of Conduct
  • ❓ Questions?
• GSSoC Contributors - Start Here
• Getting Started
• Development Setup
• Branch Naming Convention
• Code Style
• Commit Message Format
• Local Pre-PR Checks
• Pull Request Guidelines
• CI/CD Pipeline
• Reporting Issues
• Code of Conduct

---

🏅 GSSoC Contributors - Start Here

Welcome to GSSoC! Here's how the contribution flow works for this project:

1. Fork the repository to your own GitHub account (button at top-right of the repo page).
2. Clone your fork locally — never clone the upstream repo directly.
3. Work on a feature branch (not main) in your fork.
4. Open a Pull Request from your fork's branch → Checkora/Checkora:main.
5. The CI pipeline will run automatically on your PR — all checks must pass before review.
6. A maintainer will review and approve your PR. Do not merge it yourself.

Important: The main branch is protected. You cannot push directly to it — all changes must come through reviewed, approved PRs.

🔼 Back to top

---

🚀 Getting Started

1. Fork the repository on GitHub.
2. Clone your fork:

   git clone https://github.com/<your-username>/Checkora.git
   cd Checkora

3. Add upstream remote so you can stay in sync:

   git remote add upstream https://github.com/Checkora/Checkora.git
   git fetch upstream

4. Create a feature branch from main:

   git checkout -b feat/your-feature-name

🔼 Back to top

---

🛠️ Development Setup

Prerequisites

Tool	Version
Python	≥ 3.12
g++	≥ 11 (for C++ engine)
pip	latest

Installation (Windows)

# Create and activate a virtual environment
python -m venv .venv
.venv\Scripts\activate         

# Install Python dependencies
pip install -r requirements.txt

# Set up environment variables
# Copy the example file to a local .env file
copy .env.example .env           

# Compile (PowerShell with g++ installed)
g++ -O2 -std=c++17 game/engine/main.cpp -o game/engine/main.exe

# Run database migrations
python manage.py migrate

# Start the development server
python manage.py runserver

Installation (Linux/macOS)

# Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate   

# Install Python dependencies
pip install -r requirements.txt

# Set up environment variables
# Copy the example file to a local .env file
cp .env.example .env            

# Compile the C++ chess engine
g++ -O2 -std=c++17 game/engine/main.cpp -o game/engine/main
chmod +x game/engine/main

# Run database migrations
python manage.py migrate

# Start the development server
python manage.py runserver

🔼 Back to top

---

🌿 Branch Naming Convention

Use the following prefixes:

Prefix	Use for
feat/	New features
fix/	Bug fixes
docs/	Documentation changes
refactor/	Code refactoring
test/	Adding or updating tests
chore/	Maintenance tasks
engine/	C++ engine changes

Example: feat/add-move-history-panel

🔼 Back to top

---

🎨 Code Style

• Follow PEP 8 for Python code (flake8 enforces this automatically).
• Use meaningful variable and function names (no single-letter names except loop counters).
• Add docstrings to all public functions and classes.
• Keep functions focused — one function, one responsibility.
• For C++ engine code, follow the existing style in game/engine/main.cpp.

🔼 Back to top

---

📝 Commit Message Format

<scope>: <short clear action in present tense>.

Rules

• Scope: a module or feature name (game, api, ui, templates, core, engine)
• Use concise but descriptive language
• Start action with a capital letter (Fix, Add, Update, Remove, Improve)
• No emojis in commit messages
• One sentence only, ending with a period
• Keep under 80 characters

Examples

game: Add move validation for castling.
api: Fix session expiry handling in game endpoint.
templates: Update board layout for mobile responsiveness.
engine: Improve alpha-beta pruning depth limit to 6.
core: Remove deprecated settings configuration.

🔼 Back to top

---

🧪 Local Pre-PR Checks

Run these locally before creating a Pull Request.

Linting (must pass before submitting a PR)

flake8 . --exclude=.venv,migrations,__pycache__ --max-line-length=120

Django Tests

python manage.py test game --verbosity=2

Selenium E2E Tests

python manage.py test game.selenium_tests --verbosity=2

Checking for Missing Migrations

python manage.py makemigrations --check --dry-run

🔼 Back to top

---

🔀 Pull Request Guidelines

⚠️ Before starting work, sync your fork with upstream main. Opening a PR from a stale fork causes unnecessary merge conflicts. Run these steps before creating your feature branch:

# Step 1 — Sync your fork with upstream before starting work
git fetch upstream
git checkout main
git rebase upstream/main
git push origin main

# Step 2 — Then create your feature branch
git checkout -b feat/your-feature-name

1. One PR = One Purpose: fix one bug, add one feature, or improve documentation.
2. Keep PRs small and focused — large PRs are harder to review.
3. Fill in the PR template completely (it loads automatically).
4. Link the relevant issue using Fixes #<issue-number>.
5. All CI checks must pass — maintainers will not review failing PRs.
6. Add or update tests for any new functionality.
7. Update documentation (README, docstrings, comments) as needed.

Keeping Your Fork Up to Date

Before opening a PR, sync your fork with the upstream main:

git fetch upstream
git checkout main
git merge upstream/main
git push origin main
git checkout feat/your-feature-name
git rebase main

🔼 Back to top

---

⚙️ CI/CD Pipeline

Every PR and push to main runs the following automated checks via GitHub Actions:

Job	What it does	Required to merge
🔍 Lint	flake8 on all Python code	✅ Yes
⚙️ Compile Engine	g++ -O2 on game/engine/main.cpp	✅ Yes
🧪 Django Tests	python manage.py test game	✅ Yes
🗄️ Migration Check	python manage.py migrate --check	✅ Yes
🔒 Security Scan	pip-audit on requirements.txt	✅ Yes
🛡️ SAST (Bandit)	Static security analysis	✅ Yes
🖥️ Selenium Tests	End-to-end browser tests	✅ Yes
🌐 Deploy	Vercel production deploy	🔁 Push to main only

All checks must pass before a maintainer can merge your PR.

🔼 Back to top

---

🐛 Reporting Issues

When reporting issues, please include:

• A clear description of the problem
• Steps to reproduce
• Expected vs. actual behavior
• Your environment (OS, Python version, browser if UI-related)
• Relevant error messages or stack traces

Use the bug report template when opening an issue.

🔼 Back to top

---

📋 Code of Conduct

Please be respectful and considerate in all interactions. We are committed to providing a welcoming and inclusive environment for everyone.

Unacceptable behavior includes harassment, discrimination, or any form of personal attack. Violations can be reported to the project maintainers.

🔼 Back to top

---

❓ Questions?

• Open an issue for project-related questions.
• For GSSoC-specific questions, join our Discord community: https://discord.gg/WfrpMuNZn

🔼 Back to top

Thank you for contributing! ♟️🎮