Contributing to DART - Comprehensive Guide

September 6, 2026 · View on GitHub

This document provides detailed guidelines for contributing to DART, including workflow, testing, code style, and review processes.

Quick Start: For a brief overview, see the root CONTRIBUTING.md.

Table of Contents

Getting Started

Prerequisites

Before contributing, make sure you have:

  1. Development environment set up: See building.md
  2. Understanding of DART architecture: Read README.md
  3. Familiarity with code style: Check code-style.md

Finding Something to Work On

  • Browse Issues: Check GitHub Issues for open bugs or feature requests
  • Good First Issues: Look for issues labeled good first issue for newcomers
  • Feature Requests: Check GitHub Discussions for feature ideas
  • Documentation: Improving docs is always appreciated!

Contribution Workflow

1. Fork and Clone

# Fork the repository on GitHub, then clone your fork
git clone https://github.com/YOUR_USERNAME/dart.git
cd dart

# Add upstream remote
git remote add upstream https://github.com/dartsim/dart.git

2. Create a Feature Branch

# Update your main branch
git checkout main
git pull upstream main

# Create a feature branch
git checkout -b feature/my-awesome-feature

Bug Fix Workflow (Two PRs Required)

Bug fixes must be applied to both the active DART 6 LTS branch AND main to ensure fixes are available in both DART 6 and DART 7. Use the highest maintained release-6.* branch advertised by the upstream remote; this checkout currently sees release-6.20.

If evidence shows that the release branch has no affected implementation, record that evidence and the unresolved release requirement. Continue authorized local work without inventing unrelated release changes. This finding does not by itself waive the dual-PR requirement; a scope exception needs maintainer direction.

  1. Fix on release branch first:

    git fetch upstream 'refs/heads/release-6*:refs/remotes/upstream/release-6*'
DART6_LTS_BRANCH=$(git branch -r --list 'upstream/release-6.*' | sed 's|.*/||' | sort -V | tail -1)
git checkout "$DART6_LTS_BRANCH"
git pull upstream "$DART6_LTS_BRANCH"
git checkout -b "fix/issue-XXXX-description-${DART6_LTS_BRANCH#release-}"
# Make your fix, commit, and push
# Create PR targeting $DART6_LTS_BRANCH with title: "Fix: description (DART 6 LTS)"

  2. Cherry-pick to main (or reapply if conflicts):

    git checkout main
git pull upstream main
git checkout -b fix/issue-XXXX-description-main
git cherry-pick <commit-hash>  # Or manually reapply if conflicts
# Push and create PR targeting main with title: "Fix: description (DART 7)"

PR Title Convention: Use version numbers or release-line labels ("DART 6 LTS", "DART 7") rather than raw branch names for clarity.

3. Make Your Changes

  • Write code following the code style guide
  • Keep legacy files in dart/ and python/dartpy/ using PascalCase names, but use snake_case for DART 7 simulation work in dart/simulation/ and its related test/example directories (including tests/unit/simulation/ and tests/benchmark/simulation/)
  • Add tests for new functionality
  • Update documentation if needed
  • Update CHANGELOG.md when the change is notable under changelog.md, or record why no entry is needed in the PR
  • If you use docs/dev_tasks/<TASK>/ for tracking, keep it updated during work and remove the folder once the task is complete (after adding a brief note to the most relevant docs/onboarding/*.md)
  • Commit with clear, descriptive messages

4. Build and Test

pixi run build
pixi run test

Use the more focused pixi run ... test tasks documented in docs/onboarding/testing.md when a full test run is not needed. Manual CMake commands are covered in docs/onboarding/building.md for advanced build-system debugging, but contributor workflow steps should use Pixi tasks.

5. Format Your Code

pixi run lint

Rule of thumb: run pixi run lint before committing so auto-fixes are captured.

Git hooks

Run this once per clone to install the cross-tool commit guard:

pixi run install-hooks

It installs a pre-commit Git hook that runs the bounded staged-file pixi run check-agent-hook structural gate and blocks the commit if it fails. If you already have a pre-commit hook it is preserved as pre-commit.local and chained. The hook works in linked worktrees too. Emergency escape hatch: DART_SKIP_HOOKS=1 git commit ....

Claude Code and Codex sessions also use the tracked commit-command guard before an agent-issued git commit, even if the Git hook is not installed. These fast guards do not replace pixi run lint; run the full formatter before every commit as required above.

6. Push and Create Pull Request

# Push to your fork
git push origin feature/my-awesome-feature

# Create a pull request on GitHub

Use the PR template in .github/PULL_REQUEST_TEMPLATE.md and set the milestone for the target branch:

  • main: DART 7.0 (or the next major milestone)
  • Active DART 6 LTS branch, currently release-6.20: branch-matching DART 6.x release milestone

Repository Metadata Maintenance

When cleaning up GitHub issue or PR labels, treat repository metadata as a shared source of truth:

  • Prefer built-in GitHub issue types over parallel type:* labels, and update issue templates before deleting any label they still apply.
  • Use issue fields for maintainer-only scheduling data such as priority or effort, but check field visibility before replacing public labels. Removing a public label can make that signal private if the field is organization-only.
  • Keep automation labels that workflows or bots still apply, such as lockfile update, dependency, or GitHub Actions labels, unless the automation is updated in the same change.
  • Before deleting a label, verify open issue/PR usage and remember that deleting a label also removes it from closed historical issues and PRs.
  • Label, milestone, branch, and PR metadata mutations on GitHub require explicit maintainer/user approval.

Testing Requirements

All contributions must include appropriate tests:

Unit Tests

  • Located in tests/unit/
  • Use Google Test framework
  • Run with: pixi run test, pixi run test-unit, or a more focused pixi run ... test task

Integration Tests

  • Located in tests/integration/
  • Test interactions between components
  • Include in PR description

Python Tests

If modifying Python bindings:

pixi run test-py

Coverage

Check test coverage:

pixi run coverage-view

Code Review Process

Submitting a Pull Request

Commit messages and PR text are project records, not tool output: use plain descriptive titles without agent tags, and never add AI attribution anywhere in a commit message, PR description, or comment. That excludes Co-Authored-By trailers naming an AI, generated-by footers, and links to agent sessions, even when a tool's default template or a runtime instruction offers one; strip such lines before committing, and if one was already published, rewrite the commit messages over the branch and force-push with lease.

Use .github/PULL_REQUEST_TEMPLATE.md. This section owns PR-writing guidance. Write for a DART maintainer who knows the project but has not followed the task: what problem or missing capability prompted the change, how it is addressed, and what matters when reviewing it?

  • Explain the change first. Summary is the TL;DR: the concrete problem and principal change, usually one or two short sentences in prose or bullets. Aim for roughly 30–50 words total as a backstop; shorter is fine, and a count alone does not establish clarity. Give each bullet one main point instead of packing it with clauses; put secondary changes below. Name the API, solver, or workflow when it makes the change precise. "Improve robustness" describes an intention, not what the diff does.
  • Order by reviewer importance. Put material behavior changes, migration actions, and limitations beside the claims they qualify. Add rationale or Key Changes when the solution needs explanation beyond the opening. For a broad change, point to the decision or implementation area needing scrutiny. Group related changes by behavior; a file inventory or repeated Summary adds little.
  • Choose evidence for the claim. A docs or CI change needs the affected workflow and its relevant check. An API change needs the old/new usage and caller action. Physics work needs the method, correctness criterion, measured result and limits. Performance claims need a comparable baseline, workload, solver/backend configuration, hardware and accuracy tradeoffs where relevant. Keep the decisive result in the body and link reproducible supporting detail.
  • Keep Testing proportionate. State what was verified and the relevant command, test, or run link with its result, not its execution history. Keep failed, skipped, unavailable, or pending validation visible when it limits a claim or blocks required readiness/merge gates, including failures unrelated to this diff. Run all required gates; their presentation need not enumerate every formatter, routine rerun, or successful check already available in GitHub. Workflow output contracts are caller/handoff reports, not PR-body sections. Keep required audit and review provenance in existing task/session evidence; only reviewer-relevant conclusions belong here. Expandable blocks are for useful supporting detail, not a place to keep otherwise unnecessary process logs.

Summary and Testing are the default sections. Use a comparison, additional heading, or a few bold key terms when it makes the change easier to review; avoid forcing every PR into the same extended outline. Keep relevant issue, backport, and follow-up links, and the template's collapsed checklist with the milestone and short N/A reasons. Optional sections do not waive applicable migration, evidence, or backport requirements.

Simulation Evidence

For 3D structure or behavior changes, use dart-verify-sim and the simulation-verification guide. Keep the Visual verification section with the claim it explains; it can precede Testing when the behavior is central to the PR. Retain visible, assessed media, before/after comparisons with the same camera, dimensions and renderer, captions and observations, baseline identities, the text correctness oracle, verdict, claim boundaries, limitations, and reproduction commands. Follow the guide for unavailable evidence and GitHub-hosted publication; never commit transient media. Concision does not cap, collapse, or remove this required evidence.

Example And Final Read

For a hypothetical CI fix, "Improve CI efficiency and fix path filtering" is short but leaves the reviewer to discover the problem. A useful opening is:

Documentation-only PRs still run the full build matrix because excluded files match the code filter. Fix exclusion matching so those PRs skip compilation while retaining their docs and workflow checks.

Then report the filter regression check and any pending hosted verification. The example supplies context and the specific fix without listing every YAML file. A solver PR needs its numerical and visual evidence as well.

Before publication or an update, read the rendered description alongside the final diff. Can a reviewer explain the problem and solution from the opening, identify the consequential change, and find the evidence and limitations? Remove repetition and process narration; restore missing rationale or technical detail. Rewrite for the current change instead of appending its repair history.

This adapts Google's change-description guidance and GitHub's review guidance. The scientific and API emphasis fits SciPy's review guidance and Drake's checklist; DART's verification owners define the required evidence and gates.

Review Checklist

Reviewers will check:

  • Code follows style guide
  • Tests are included and pass
  • Documentation is updated
  • No unnecessary changes (keep PRs focused)
  • Commit messages are clear
  • No merge conflicts

Addressing Feedback

  • Be responsive to reviewer comments
  • Make requested changes in new commits (don't force-push)
  • If the PR needs the latest target branch, use explicit maintainer/user approval to merge that branch into the PR branch instead of rebasing the published PR history
  • Mark conversations as resolved when addressed
  • Ask questions if feedback is unclear

Merging

  • PRs are typically merged by maintainers
  • Squash merging is used for clean history
  • Your contribution will be acknowledged!

Release Process

DART follows semantic versioning (MAJOR.MINOR.PATCH):

  • MAJOR: Breaking API changes
  • MINOR: New features (backward compatible)
  • PATCH: Bug fixes (backward compatible)

Releases are managed by project maintainers. Contributors don't need to worry about versioning.

Contributors

DART is developed by a diverse community of researchers and engineers from around the world.

Core Team

NameContributions
C. Karen LiuProject creator, multibody dynamics, constraint resolution, tutorials
Mike StilmanProject creator
Siddhartha S. SrinivasaProject advisor
Jeongseok LeeProject director, multibody dynamics, constraint resolution, collision detection, tutorials
Michael X. GreyProject director, extensive API improvements, inverse kinematics, gui, tutorials
Tobias KunzFormer project director, motion planner

Major Contributors

NameContributions
Sumit JainMultibody dynamics
Yuting YeMultibody dynamics, GUI
Michael KovalURI, resource retriever, bug fixes
Ana C. Huamán QuispeURDF parser
Chen TangCollision detection
Konstantinos ChatzilygeroudisMimic joint, OSG shadows, shape deep copy, build and bug fixes
Sehoon HaEarly DART data structure design, pydart
Addisu TaddeseODE collision detector, slip effect, velocity/position integration, constraint grouping
Christoph HinzePython bindings
Silvio TraversaroBuild fixes on Windows/MSVC, vcpkg packaging

Community Contributors

Many others have contributed bug fixes, documentation, and improvements:

You can find the complete contribution history in the GitHub contributors page.

Institutional Support

DART has been supported by various institutions:

  • Humanoid Lab, Georgia Tech Research Corporation
  • Personal Robotics Lab, Carnegie Mellon University
  • Graphics Lab, Georgia Tech Research Corporation
  • Personal Robotics Lab, University of Washington
  • Open Source Robotics Foundation
  • The Movement Lab, Stanford University

PR Readiness Checklist

Before submitting your pull request, verify:

  • Code follows style guide (pixi run lint passes)
  • Tests are included for new functionality
  • All tests pass (pixi run test shows "100% tests passed")
  • Documentation is updated if needed
  • Commit messages are clear and descriptive
  • No merge conflicts with main branch
  • PR description leads with a concise summary and reports testing outcomes
  • PR description uses .github/PULL_REQUEST_TEMPLATE.md
  • Milestone is set for the target branch (DART 7.0 for main, branch-matching DART 6.x release milestone for the active DART 6 LTS branch)
  • CHANGELOG.md is updated according to changelog.md, or the PR records why no entry is needed
  • Bug fixes that apply to the release line have an active-DART-6-LTS PR first, then a main PR
  • Any docs/dev_tasks/<task>/ folder used for tracking is removed after durable notes move to the owner selected by docs/README.md

Getting Help

If you need help with contributing:

License

By contributing to DART, you agree that your contributions will be licensed under the BSD 2-Clause License. See the LICENSE file for details.

Thank you for contributing to DART! Your efforts help advance robotics research and development worldwide.