| # Contributing to UGTC |
|
|
| Thank you for your interest in contributing to UGTC! |
|
|
| ## Getting Started |
|
|
| ```bash |
| git clone https://github.com/ethosoftai/ugtc.git |
| cd ugtc |
| pip install -e ".[dev]" |
| ``` |
|
|
| ## Development Setup |
|
|
| ```bash |
| pip install ruff black isort mypy pytest pytest-cov |
| ``` |
|
|
| ## Running Tests |
|
|
| ```bash |
| 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 |
|
|
| ```bash |
| 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](https://doi.org/10.5281/zenodo.19715116) 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](CODE_OF_CONDUCT.md). |
|
|
