Submit a Pull Request

This guide walks you through submitting a pull request to Babylon, from branching to merge.

Prerequisites

  • Git installed and configured

  • Repository cloned: git clone https://github.com/percy-raskova/babylon.git

  • Poetry installed: pip install poetry

  • Dependencies installed: poetry install

  • Pre-commit hooks installed: poetry run pre-commit install

Branch from dev

All contributions branch from dev, not main:

# Ensure you're on dev and up to date
git checkout dev
git pull origin dev

# Create your feature branch
git checkout -b feature/your-feature-name

Branch naming conventions:

Prefix

Purpose

Example

feature/

New functionality

feature/solidarity-decay

fix/

Bug fixes

fix/ideology-overflow

docs/

Documentation

docs/add-topology-guide

refactor/

Code improvements

refactor/simplify-survival

test/

Test changes

test/add-formula-coverage

Make Your Changes

  1. Write code following project standards:

    • Type hints on all functions

    • Docstrings in RST format

    • No hardcoded values (use GameDefines)

  2. Run pre-commit hooks (automatic on commit):

    # Manual run
poetry run pre-commit run --all-files

  3. Run tests to ensure nothing breaks:

    # Fast tests (recommended during development)
poetry run pytest -m "not ai" --tb=short

# Or use mise
mise run test

Commit Your Changes

Use Conventional Commits format:

git add .
git commit -m "feat(topology): add solidarity edge decay"

Commit types:

  • feat: - New feature

  • fix: - Bug fix

  • docs: - Documentation only

  • refactor: - Code change that neither fixes nor adds

  • test: - Adding or correcting tests

  • chore: - Maintenance tasks

Push and Create PR

# Push your branch
git push -u origin feature/your-feature-name

Then on GitHub:

  1. Navigate to the repository

  2. Click “Compare & pull request”

  3. Target branch: Select dev (not main)

  4. Fill out the PR template

  5. Submit

The PR Template

The template asks for:

## What does this PR do?
Brief description of the change.

## Related Issue
Link to issue if applicable, or "N/A".

## Checklist
- [ ] I've tested my changes locally
- [ ] My code follows the existing style
- [ ] I've updated documentation if needed

## Questions for Reviewers
Anything you're unsure about?

Tip

The checklist is a guide, not a gate. Don’t stress if you can’t check every box—the maintainer can help clean things up.

What Happens Next

  1. CI runs automatically on your PR:

    • Lint check (Ruff)

    • Type check (MyPy)

    • Tests (Pytest)

    • Documentation build (Sphinx)

  2. Review CI results:

    • Green ✓ = all checks pass

    • Red ✗ = something needs fixing (see logs)

    • Yellow ⚠ = advisory only (style suggestions)

  3. Maintainer reviews and may:

    • Approve and merge

    • Request changes

    • Fix minor issues during merge

  4. Celebrate when merged! 🎉

Handling CI Failures

If CI fails, don’t panic:

Lint failures (Ruff)
poetry run ruff check . --fix
git add . && git commit -m "fix: address lint issues"
Type failures (MyPy)

Check the error message for missing type hints or type mismatches. See Error Codes for common issues.

Test failures (Pytest)
# Run the specific failing test
poetry run pytest tests/path/to/test.py -v
Documentation failures (Sphinx)

Usually a malformed docstring. Check for RST syntax issues.

Note

Style check failures (yellow warnings) won’t block your PR. The maintainer can fix formatting during merge.

Keeping Your Branch Updated

If dev moves forward while you’re working:

git checkout dev
git pull origin dev
git checkout feature/your-feature-name
git rebase dev

# If conflicts, resolve them, then:
git push --force-with-lease

See Also