Contributing Guide¶

Welcome to RLightning. This guide covers the expected development workflow for contributions to the project.

Types of Contributions¶

We welcome the following types of contributions:

Bug Reports

Use GitHub Issues to report bugs
Include a minimal reproducible example
Specify your environment (Python version, OS, CUDA version if applicable)
Describe expected vs. actual behavior

Bug Fixes

Reference the related issue in your PR
Keep changes focused and minimal
Document how you validated the fix

Documentation

Fix typos, clarify explanations, add examples
Ensure code examples stay runnable
Follow the existing documentation style

New Features

Discuss major features in an issue before implementation
Follow the existing architecture patterns
Include documentation for new user-facing behavior

Performance Improvements

Include benchmarks showing the improvement
Call out any tradeoffs or assumptions

Development Setup¶

Prerequisites¶

Python 3.11 or higher
Git with submodule support
uv package manager (recommended)

Clone the Repository¶

git clone --recursive https://github.com/DeepLink-org/RLightning.git
cd RLightning

The --recursive flag ensures submodules (for example third_party/rsl_rl) are initialized.

Install Dependencies¶

For core development:

uv sync --extra dev

For environment-specific development, add the corresponding extra:

# ALE/Atari environments
uv sync --extra dev --extra ale

# MuJoCo environments
uv sync --extra dev --extra mujoco

# Isaac Lab environments
uv sync --extra dev --extra isaaclab

# ManiSkill environments
uv sync --extra dev --extra maniskill

Note

Some extras have conflicts (for example isaaclab conflicts with mujoco and maniskill). Use separate virtual environments for conflicting extras.

Virtual Environment Management¶

The project uses isolated virtual environments in .venvs/ for different dependency sets:

make install-core
make install-ale
make install-mujoco
make install-isaaclab
make install-maniskill
make install-rslrl

Verify Installation¶

uv run python -c "import rlightning"

Code Style¶

Formatting¶

We use isort with the Black profile for import sorting:

# Sort imports
uv run isort rlightning/ examples/

# Check without modifying
uv run isort --check-only rlightning/ examples/

The isort configuration is in pyproject.toml:

[tool.isort]
profile = "black"
known_first_party = ["rlightning"]

Type Hints¶

Add type hints to all public functions and methods
Use typing module for complex types
Prefer built-in generics (list[int] over List[int]) for Python 3.11+

Example:

def process_batch(
    observations: torch.Tensor,
    actions: torch.Tensor,
    rewards: list[float],
) -> dict[str, torch.Tensor]:
    """Process a batch of transitions."""
    ...

Docstrings¶

Use Google-style docstrings for all public APIs:

def compute_returns(
    rewards: torch.Tensor,
    dones: torch.Tensor,
    gamma: float = 0.99,
) -> torch.Tensor:
    """Compute discounted returns from rewards.

    Args:
        rewards: Tensor of shape (T, N) containing rewards.
        dones: Tensor of shape (T, N) containing episode termination flags.
        gamma: Discount factor. Defaults to 0.99.

    Returns:
        Tensor of shape (T, N) containing discounted returns.

    Raises:
        ValueError: If rewards and dones have different shapes.
    """
    ...

General Guidelines¶

Keep lines under 100 characters
Use descriptive variable names
Prefer composition over inheritance
Avoid global state and singletons
Use pathlib.Path over string paths
Keep documentation in sync with behavioral changes

Git Workflow¶

Branch Naming¶

Use the following prefixes for branch names:

Prefix	Purpose	Example
`feat/`	New features	`feat/async-rollout`
`fix/`	Bug fixes	`fix/buffer-overflow`
`refactor/`	Code refactoring	`refactor/engine-simplify`
`docs/`	Documentation changes	`docs/api-reference`
`chore/`	Maintenance tasks	`chore/dependency-refresh`

Branching Model¶

develop: Main development branch. All feature branches merge here.
main/master: Production-ready code. Only release merges.

Commit Messages¶

Write clear, descriptive commit messages:

<type>: <subject>

<body>

Types:

feat: New feature
fix: Bug fix
docs: Documentation only
refactor: Code refactoring
chore: Maintenance tasks

Submitting Changes¶

Before Submitting¶

Sync with upstream:

git fetch origin
git rebase origin/develop

Run the relevant command path for your change:
```
uv run python -c "import rlightning"
```

Check code style:

uv run isort --check-only rlightning/ examples/

Update documentation if needed:

cd docs
../.venv-docs/bin/sphinx-build -b html source build/html -W

Creating a Pull Request¶

Push your branch:
```
git push origin feat/your-feature
```
Create a PR targeting the develop branch
Fill in the PR template:
- Summary: Brief description of changes
- Related Issue: Link to related issue (if any)
- Validation: How the changes were checked
- Checklist: Confirm docs updated and notes are accurate

PR Review Process¶

Maintainer review: Changes are reviewed for correctness and style
Validation review: Reviewers may ask for runtime or documentation validation details
Address feedback: Push additional commits to address comments
Approval: Once approved, maintainers will merge

Note

Keep PRs focused and reasonably sized. Large PRs are harder to review and more likely to have conflicts.

Documentation¶

Building Documentation¶

cd docs

# Using the docs virtual environment
../.venv-docs/bin/sphinx-build -b html source build/html

# Preview locally
cd build/html
python -m http.server 8000
# Visit http://localhost:8000

Documentation Style¶

Use reStructuredText (.rst) format
Include code examples with .. code-block::
Add cross-references with :ref: and :doc:
Document all public APIs with docstrings

API Documentation¶

When source code changes affect public APIs, regenerate API documentation:

cd docs
../.venv-docs/bin/sphinx-apidoc -o source/api/_generated ../rlightning        --force --separate --module-first -e

Getting Help¶

If you have questions or need help:

GitHub Issues: For bug reports and feature requests
GitHub Discussions: For questions and general discussion
Documentation: Check existing docs for answers