Contributing

We welcome contributions to Cubs2! This guide will help you get started.

Development Setup

Clone and Build

# Clone repository
git clone https://github.com/cognipilot/cubs2.git
cd cubs2

# Install dependencies
sudo apt install ros-jazzy-desktop qtbase5-dev libgstreamer1.0-dev
pip install numpy scipy casadi cyecca

# Build
colcon build --symlink-install

# Source workspace
source install/setup.bash

Code Style

Python

We follow PEP 8 with some modifications:

Line length: 100 characters
Use Black for formatting
Use isort for import sorting

# Format code
black cubs2_dynamics/ cubs2_control/ cubs2_planning/

# Sort imports
isort cubs2_dynamics/ cubs2_control/ cubs2_planning/

C++

We follow Google C++ Style Guide:

Line length: 100 characters
Use clang-format

# Format C++ code
find cubs2_rviz/src -name "*.cpp" -o -name "*.hpp" | xargs clang-format -i

Linting

# Python
flake8 cubs2_dynamics/ cubs2_control/ cubs2_planning/

# C++
ament_cpplint cubs2_rviz/

Testing

Unit Tests

# Run all tests
colcon test

# Run specific package
colcon test --packages-select cubs2_dynamics

# View results
colcon test-result --verbose

Coverage

# Run with coverage
colcon test --pytest-args --cov=cubs2_dynamics --cov-report=html

# View report
firefox build/cubs2_dynamics/coverage_html/index.html

Integration Tests

# Launch full system
ros2 launch cubs2_bringup sim.xml

# In another terminal, run integration tests
pytest tests/integration/

Pull Request Process

1. Fork the Repository

Click “Fork” on GitHub and clone your fork:

git clone https://github.com/YOUR_USERNAME/cubs2.git
cd cubs2
git remote add upstream https://github.com/cognipilot/cubs2.git

2. Create a Branch

git checkout -b feature/my-new-feature

Use branch naming:

feature/ - New features
fix/ - Bug fixes
docs/ - Documentation
refactor/ - Code refactoring

3. Make Changes

Write code following style guidelines
Add tests for new functionality
Update documentation
Keep commits atomic and well-described

4. Run Tests

# Format code
black .
isort .

# Lint
flake8 .

# Test
colcon test
colcon test-result

5. Submit Pull Request

git push origin feature/my-new-feature

Then open a pull request on GitHub with:

Clear description of changes
Reference to related issues
Screenshots/videos if applicable

Code Review

Checklist

Reviewers will check:

✓ Code follows style guide
✓ Tests pass
✓ Documentation updated
✓ No breaking changes (or properly documented)
✓ Commit messages are clear

Addressing Feedback

# Make requested changes
git add .
git commit -m "Address review comments"
git push origin feature/my-new-feature

Documentation

Building Docs

cd docs
make html
firefox _build/html/index.html

Writing Docstrings

Use NumPy style:

def my_function(param1, param2):
    """
    Brief description.

    Longer description if needed.

    Parameters
    ----------
    param1 : float
        Description of param1
    param2 : str
        Description of param2

    Returns
    -------
    bool
        Description of return value

    Examples
    --------
    >>> my_function(1.0, "test")
    True
    """
    return True

License

By contributing, you agree that your contributions will be licensed under the Apache-2.0 License.

Questions?

Open an issue on GitHub
Join our Discord: [link]
Email: [email]