# 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).