Contributing to nanobot

Contributing to nanobot

Thank you for being here.

nanobot is built with a simple belief: good tools should feel calm, clear, and humane. We care deeply about useful features, but we also believe in achieving more with less: solutions should be powerful without becoming heavy, and ambitious without becoming needlessly complicated.

This guide is not only about how to open a PR. It is also about how we hope to build software together: with care, clarity, and respect for the next person reading the code.

Maintainers

Maintainer	Focus
@re-bin	Project lead, main branch
@chengyongru	nightly branch, experimental features

Branching Strategy

We use a two-branch model to balance stability and exploration:

Branch	Purpose	Stability
main	Stable releases	Production-ready
nightly	Experimental features	May have bugs or breaking changes

Which Branch Should I Target?

**Target `nightly` if your PR includes:**

• New features or functionality
• Refactoring that may affect existing behavior
• Changes to APIs or configuration

**Target `main` if your PR includes:**

• Bug fixes with no behavior changes
• Documentation improvements
• Minor tweaks that don't affect functionality

**When in doubt, target `nightly`.** It is easier to move a stable idea from `nightly` to `main` than to undo a risky change after it lands in the stable branch.

How Does Nightly Get Merged to Main?

We don't merge the entire `nightly` branch. Instead, stable features are **cherry-picked** from `nightly` into individual PRs targeting `main`:

nightly  ──┬── feature A (stable) ──► PR ──► main
           ├── feature B (testing)
           └── feature C (stable) ──► PR ──► main

This happens approximately **once a week**, but the timing depends on when features become stable enough.

Quick Summary

Your Change	Target Branch
New feature	nightly
Bug fix	main
Documentation	main
Refactoring	nightly
Unsure	nightly

Development Setup

Keep setup boring and reliable. The goal is to get you into the code quickly:

# Clone the repository
git clone https://github.com/HKUDS/nanobot.git
cd nanobot

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Lint code
ruff check nanobot/

# Format code
ruff format nanobot/

Code Style

We care about more than passing lint. We want nanobot to stay small, calm, and readable.

When contributing, please aim for code that feels:

• Simple: prefer the smallest change that solves the real problem
• Clear: optimize for the next reader, not for cleverness
• Decoupled: keep boundaries clean and avoid unnecessary new abstractions
• Honest: do not hide complexity, but do not create extra complexity either
• Durable: choose solutions that are easy to maintai