Skip to content

contribution-guide.md

Latest commit

 

History

History
427 lines (278 loc) · 14.5 KB

contribution-guide.md

File metadata and controls

427 lines (278 loc) · 14.5 KB
subtitle How to contribute to Dynamo
max-toc-depth 3

Contribution Guide

Dynamo is an open-source distributed inference platform, built by a growing community of contributors. The project is licensed under Apache 2.0 and welcomes contributions of all sizes -- from typo fixes to major features. Community contributions have shaped core areas of Dynamo including backend integrations, documentation, deployment tooling, and performance improvements.

With 200+ external contributors, 220+ merged community PRs, and new contributors joining every month, Dynamo is one of the fastest-growing open-source inference projects. Check out our commit activity and GitHub stars. This guide will help you get started.

Join the community:

TL;DR

For experienced contributors:

  1. Fork and clone the repo
  2. For changes ≥100 lines or new features, open an issue first
  3. Create a branch: git checkout -b yourname/fix-router-timeout
  4. Make changes, run pre-commit run
  5. Commit with DCO sign-off: git commit -s -m "fix: description"
  6. Open a PR targeting main

Ways to Contribute

Report a Bug

Found something broken? Open a bug report with:

  • Steps to reproduce
  • Expected vs. actual behavior
  • Environment details (OS, GPU, Python version, Dynamo version)

Improve Documentation

Documentation improvements are always welcome:

  • Fixing typos or unclear explanations
  • Adding examples or tutorials
  • Improving API documentation

Small doc fixes can be submitted directly as PRs without an issue.

Propose a Feature

Have an idea? Open a feature request to discuss it with maintainers before implementation.

Contribute Code

Ready to write code? See the Contribution Workflow section below.

Help the Community

Not all contributions are code. You can also:

  • Answer questions on Discord or CNCF Slack
  • Review pull requests
  • Share how you're using Dynamo -- blog posts, talks, or social media
  • Star the repository

Getting Started

Find an Issue

Browse open issues or look for:

Issue Type Description
Good First Issues Beginner-friendly, with guidance
Help Wanted Community contributions welcome

Fork and Clone

  1. Fork the repository on GitHub
  2. Clone your fork:
git clone https://github.com/YOUR-USERNAME/dynamo.git
cd dynamo
git remote add upstream https://github.com/ai-dynamo/dynamo.git

Building from Source

Tip

Full build instructions are included below. Expand the accordion to set up your local development environment.

Expand build instructions

1. Install System Libraries

Ubuntu:

sudo apt install -y build-essential libhwloc-dev libudev-dev pkg-config libclang-dev protobuf-compiler python3-dev cmake

macOS:

# Install Homebrew if needed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

brew install cmake protobuf

# Verify Metal is accessible
xcrun -sdk macosx metal

2. Install Rust

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

3. Create a Python Virtual Environment

Install uv if you don't have it:

curl -LsSf https://astral.sh/uv/install.sh | sh

Create and activate a virtual environment:

uv venv .venv
source .venv/bin/activate

4. Install Build Tools

uv pip install pip maturin

Maturin is the Rust-Python bindings build tool.

5. Build the Rust Bindings

cd lib/bindings/python
maturin develop --uv

6. Install GPU Memory Service

# Return to project root
cd "$(git rev-parse --show-toplevel)"
uv pip install -e lib/gpu_memory_service

7. Install the Wheel

uv pip install -e .

8. Verify the Build

python3 -m dynamo.frontend --help

[!TIP] VSCode and Cursor users can use the .devcontainer folder for a pre-configured development environment. See the devcontainer README for details.

Set Up Pre-commit Hooks

uv pip install pre-commit
pre-commit install

You're all set up! Get curious -- explore the codebase, experiment with the examples, and see how the pieces fit together. When you're ready, pick an issue from the Good First Issues board or read on for the full contribution workflow.

Contribution Workflow

The contribution process depends on the size and scope of your change. Even when not required, opening an issue is a great way to start a conversation with Dynamo maintainers before investing time in a PR.

Size Lines Changed Example What You Need
XS 1–10 Typo fix, config tweak Submit a PR directly
S 10–100 Small bug fix, doc improvement, focused refactor Submit a PR directly
M 100–200 Feature addition, moderate refactor Open an issue first
L 200–500 Multi-file feature, new component Open an issue first
XL 500–1000 Major feature, cross-component change Open an issue first
XXL 1000+ Architecture change Requires a DEP

Small changes (under 100 lines): Submit a PR directly -- no issue needed. This includes typos, simple bug fixes, and formatting. If your PR addresses an existing approved issue, link it with "Fixes #123".

Larger changes (≥100 lines): Open a Contribution Request issue first and wait for the approved-for-pr label before submitting a PR.

Architecture changes: Changes that affect multiple components, introduce or modify public APIs, alter communication plane architecture, or affect backend integration contracts require a Dynamo Enhancement Proposal (DEP). Open a DEP in the ai-dynamo/enhancements repo before starting implementation.

Submitting a Pull Request

  1. Create a GitHub Issue (if required) — Open a Contribution Request and describe what you're solving, your proposed approach, estimated PR size, and files affected.

  2. Get Approval — Wait for maintainers to review and apply the approved-for-pr label.

  3. Submit a Pull Request — Open a PR that references the issue using GitHub keywords (e.g., "Fixes #123").

  4. Address Code Rabbit Review — Respond to automated Code Rabbit suggestions, including nitpicks.

  5. Trigger CI Tests — For external contributors, a maintainer must comment /ok to test COMMIT-ID to run the full CI suite, where COMMIT-ID is the short SHA of your latest commit. Fix any failing tests before requesting human review.

  6. Request Review — Add the person who approved your issue as a reviewer. Check CODEOWNERS for required approvers based on files modified.

Important

AI-Generated Code: While we encourage using AI tools, you must fully understand every change in your PR. Inability to explain submitted code will result in rejection.

Branch Naming

Use a descriptive branch name that identifies you and the change:

yourname/fix-description

Examples:

jsmith/fix-router-timeout
jsmith/add-lora-support

Code Style & Quality

Maintainers assess contribution quality based on code style, test coverage, architecture alignment, and review responsiveness. Consistent, high-quality contributions are the foundation for building trust in the project.

Pre-commit Hooks

All PRs are checked against pre-commit hooks. After installing pre-commit, run checks locally:

pre-commit run --all-files

Commit Message Conventions

Use conventional commit prefixes:

Prefix Use For
feat: New features
fix: Bug fixes
docs: Documentation changes
refactor: Code refactoring (no behavior change)
test: Adding or updating tests
chore: Maintenance, dependency updates
ci: CI/CD changes
perf: Performance improvements

Examples:

feat(router): add weighted load balancing
fix(frontend): resolve streaming timeout on large responses
docs: update quickstart for macOS users
test(planner): add unit tests for scaling policy

Language Conventions

Language Style Guide Formatter
Python PEP 8 black, ruff
Rust Rust API Guidelines cargo fmt, cargo clippy
Go Effective Go gofmt

Testing

Run the test suite before submitting a PR:

# Run all tests
pytest tests/

# Run unit tests only
pytest -m unit tests/

# Run a specific test file
pytest -s -v tests/test_example.py

For Rust components:

cargo test

For the Kubernetes operator (Go):

cd deploy/operator
go test ./... -v

General Guidelines

  • Keep PRs focused -- one concern per PR
  • Write clean, well-documented code that future contributors can understand
  • Include tests for new functionality and bug fixes
  • Ensure clean builds (no warnings or errors)
  • All tests must pass
  • No commented-out code
  • Respond to review feedback promptly and constructively

Running GitHub Actions Locally

Use act to run workflows locally:

act -j pre-merge-rust

Or use the GitHub Local Actions VS Code extension.

What to Expect

Status Labels

Status What It Means
needs-triage We're reviewing your issue
needs-info We need more details from you
approved-for-pr Ready for implementation — submit a PR
in-progress Someone is working on this
blocked Waiting on external dependency

Response Times

We aim to:

  • Respond to new issues within a few business days
  • Triage high-priority issues within a week

Issues with no activity for 30 days may be auto-closed (can be reopened).

Review Process

After you submit a PR and complete the steps in Submitting a Pull Request:

  1. The reviewer will provide feedback -- please respond to all comments within a reasonable timeframe
  2. If changes are requested, address them and ping the reviewer for re-review
  3. If your PR hasn't been reviewed within 7 days, feel free to ping the reviewer or leave a comment

Good First Issues

Issues labeled good-first-issue are sized for new contributors. We provide extra guidance on these -- look for clear acceptance criteria and a suggested approach in the issue description.

DCO & Licensing

Developer Certificate of Origin

Dynamo requires all contributions to be signed off with the Developer Certificate of Origin (DCO). This certifies that you have the right to submit your contribution under the project's Apache 2.0 license.

Each commit must include a sign-off line:

Signed-off-by: Jane Smith <[email protected]>

Add this automatically with the -s flag:

git commit -s -m "fix: your descriptive message"

Requirements:

  • Use your real name (no pseudonyms or anonymous contributions)
  • Your user.name and user.email must be configured in git

DCO Check Failed? See our DCO Troubleshooting Guide for step-by-step instructions to fix it.

License

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

Code of Conduct

We are committed to providing a welcoming and inclusive environment. All participants are expected to abide by our Code of Conduct.

Security

If you discover a security vulnerability, please follow the instructions in our Security Policy. Do not open a public issue for security vulnerabilities.

Getting Help

Thank you for contributing to Dynamo!