Contributing to repogym

Thanks for your interest! repogym is small on purpose, and contributions that keep it small, well-tested and well-documented are very welcome.

Development setup

git clone https://github.com/shi1720/repogym
cd repogym
python -m venv .venv && source .venv/bin/activate   # or: uv venv && source .venv/bin/activate
pip install -e ".[dev,docs]"
repogym doctor

Running the checks

ruff check src tests && ruff format --check src tests   # lint + formatting
mypy                                                     # types
python -m pytest                                         # tests (add -m "not slow" to skip the perf task)
repogym validate tasks                                   # every shipped task must stay sound
mkdocs serve                                             # docs at http://127.0.0.1:8000

CI runs the same commands on Linux and macOS across Python 3.9 - 3.13.

What makes a good contribution

• New graders / actions / sandboxes - implement the small base class, add tests, document it in docs/guides/.
• New example tasks - put them under tasks/, make sure repogym validate tasks --repeat 2 passes, keep repositories tiny.
• Language support - anything that emits JUnit XML already works; a PR that adds a documented example task for Rust/Go/Java plus a CI matrix entry is ideal.
• Bug reports - include the task.yaml, the command you ran and the output of repogym validate -v.

Style

• Python 3.9+ compatible (no match, no X | Y unions at runtime).
• Type hints everywhere; mypy must stay green.
• Public behaviour gets a test. Prefer end-to-end tests through the real Workspace/RepoEnv over mocks.
• Keep the dependency list short (pydantic, typer, rich, pyyaml). Anything heavier goes behind an optional extra.

Commit messages

Conventional-ish: feat:, fix:, docs:, test:, refactor:, chore:.

Releasing

1. Bump version in pyproject.toml and __version__ in src/repogym/__init__.py.
2. Update CHANGELOG.md.
3. Tag vX.Y.Z and push; the release workflow builds and publishes to PyPI.