CONTRIBUTING.md

Contributing to UGTC

Thank you for your interest in contributing to UGTC!

Getting Started

git clone https://github.com/ethosoftai/ugtc.git
cd ugtc
pip install -e ".[dev]"

Development Setup

pip install ruff black isort mypy pytest pytest-cov

Running Tests

pytest tests/ -v
pytest tests/ -v --cov=ugtc --cov-report=html

Code Style

We use:

• black for formatting (line length 100)
• isort for import ordering
• ruff for linting
• mypy for type checking

black ugtc/ tests/ examples/
isort ugtc/ tests/ examples/
ruff check ugtc/ tests/ examples/
mypy ugtc/ --ignore-missing-imports

Types of Contributions

Bug Reports

Open an issue with:

• Minimal reproducible example
• Expected vs actual behavior
• Python/PyTorch/OS version

New RL Algorithm Integrations

When adding a new RL backbone integration (e.g., UGTC-IMPALA):

1. Create ugtc/impala.py following the pattern of ugtc/ppo.py
2. Add integration tests to tests/test_integrations.py
3. Add an example to examples/
4. Clearly label if the integration is from the paper or a proposed extension

New Benchmark Scripts

Add to benchmarks/ with:

• Clear docstring explaining the experiment
• Config at the top of the file
• Full standalone runnable script

Documentation

• Improve docs/index.html
• Fix typos in README or pseudocode

Transparency Requirements

UGTC is a published research codebase. Please:

1. Do not fabricate benchmark numbers. If you run experiments and get results, share them as your own empirical findings, not as paper claims.
2. Label assumptions. If you implement an extension not described in the paper, mark it with # NOTE: implementation extension — not in paper.
3. Cite correctly. Reference the paper when using this work.

Pull Request Process

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Commit changes with clear messages
4. Ensure all tests pass and linting is clean
5. Open a PR with a description of what changed and why

Code of Conduct

This project follows the Contributor Covenant.