Skip to content

Contributing to Gym

Thank you for your interest in contributing to Gym! As a project by Zoo Labs Foundation (501©(3) non-profit), we welcome contributions from the community.

How to Contribute

Types of Contributions

  • Code: Bug fixes, new features, performance improvements
  • Documentation: Tutorials, API docs, examples
  • Datasets: High-quality training data
  • Bug Reports: Issues you encounter
  • Feature Requests: Ideas for improvements
  • Community Support: Helping others on Discord/GitHub

Getting Started

Development Setup

  1. Fork the repository 

    # Click "Fork" on GitHub, then:
git clone https://github.com/YOUR-USERNAME/gym.git
cd gym

  2. Create development environment 

    python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -e ".[dev]"

  3. Install pre-commit hooks 

    pre-commit install

  4. Create a branch 

    git checkout -b feature/my-feature
# or
git checkout -b fix/my-bugfix

Making Changes

  1. Write code
  2. Follow PEP 8 style guide
  3. Add type hints
  4. Include docstrings

  5. Keep functions focused and small

  6. Add tests 

    # Create test file
tests/test_my_feature.py

# Run tests
pytest tests/test_my_feature.py -v

  7. Update documentation

  8. Add docstrings to new functions
  9. Update relevant .md files

  10. Add examples if applicable

  11. Run checks 

    # Format code
black src/

# Check types
mypy src/

# Lint
ruff check src/

# Test
pytest tests/ -v

Submitting Changes

  1. Commit your changes 
    git add .
git commit -m "feat: Add new training method"

Follow Conventional Commits: - feat: New feature - fix: Bug fix - docs: Documentation - test: Tests - refactor: Code refactoring - perf: Performance improvement - chore: Maintenance

  1. Push to your fork 

    git push origin feature/my-feature

  2. Create Pull Request

  3. Go to GitHub and click "New Pull Request"
  4. Fill in PR template
  5. Link related issues
  6. Request review

Code Style

Python Style

"""Module docstring explaining purpose."""

from typing import Optional, List
import torch


class MyTrainer:
    """Class docstring with description.

    Args:
        model: The model to train
        config: Training configuration

    Example:
        >>> trainer = MyTrainer(model, config)
        >>> trainer.train()
    """

    def __init__(self, model: torch.nn.Module, config: dict) -> None:
        """Initialize trainer."""
        self.model = model
        self.config = config

    def train(self, epochs: int = 3) -> dict:
        """Train the model.

        Args:
            epochs: Number of training epochs

        Returns:
            Dictionary with training metrics
        """
        # Implementation
        pass

Documentation Style

  • Use Markdown for all docs
  • Include code examples that work
  • Add screenshots where helpful
  • Cross-reference related docs
  • Keep paragraphs short and scannable

Testing

Running Tests

# All tests
pytest tests/ -v

# Specific test file
pytest tests/test_trainer.py -v

# With coverage
pytest tests/ --cov=gym --cov-report=html

# Specific test function
pytest tests/test_trainer.py::test_basic_training -v

Writing Tests

"""Test module for new feature."""

import pytest
from gym.train import MyTrainer


def test_trainer_initialization():
    """Test trainer can be initialized."""
    trainer = MyTrainer(model, config)
    assert trainer.model is not None


def test_training_loop():
    """Test training completes successfully."""
    trainer = MyTrainer(model, config)
    result = trainer.train(epochs=1)
    assert "loss" in result
    assert result["loss"] < 10.0


@pytest.mark.slow
def test_full_training():
    """Test complete training pipeline."""
    # Long-running test
    pass

Documentation

Building Docs Locally

# Install docs dependencies
pip install -r requirements-docs.txt

# Build docs
mkdocs build

# Serve docs locally
mkdocs serve
# Open http://localhost:8000

Adding New Documentation

  1. Create .md file in docs/
  2. Add to mkdocs.yml navigation
  3. Follow existing structure
  4. Include code examples
  5. Add cross-references

Review Process

What We Look For

  • Functionality: Does it work as intended?
  • Tests: Are there tests? Do they pass?
  • Documentation: Is it documented?
  • Code Quality: Is it clean and maintainable?
  • Performance: Does it affect performance?
  • Breaking Changes: Does it break existing code?

Review Timeline

  • Initial review: 1-3 days
  • Follow-up reviews: 1-2 days
  • Merge: After approval and CI passes

Community Guidelines

Code of Conduct

  • Be respectful and inclusive
  • Welcome newcomers
  • Give constructive feedback
  • Credit others' work
  • Report unacceptable behavior to conduct@zoo.ngo

Communication

  • GitHub Issues: Bug reports, feature requests
  • GitHub Discussions: Questions, ideas
  • Discord: Real-time chat, community support
  • Email: Private matters (support@zoo.ngo)

Recognition

Contributors

All contributors are: - Listed in CONTRIBUTORS.md - Credited in release notes - Eligible for swag (stickers, shirts) - Invited to contributor calls

Significant Contributions

Major contributions may receive: - Co-authorship on papers - Speaking opportunities - Grants for continued work - Tax-deductible donation receipts (501©(3))

Contributor License Agreement

By contributing, you agree that: - Your contributions are your own work - You grant Zoo Labs Foundation rights to use/distribute - Your contributions are under Apache 2.0 license - You have rights to make the contribution

Copyright (c) 2025 Zoo Labs Foundation Inc

Licensed under the Apache License, Version 2.0

Questions?

Thank you for contributing to democratizing AI! 🎉