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/

Contribution License

By submitting a contribution, you confirm that you have the right to submit it and agree that it will be licensed under the project's MIT License.

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 maintain, test, and extend

In practice:

Line length: 100 characters (ruff)
Target: Python 3.11+
Linting: ruff with rules E, F, I, N, W (E501 ignored)
Async: uses asyncio throughout; pytest with asyncio_mode = "auto"
Prefer readable code over magical code
Prefer focused patches over broad rewrites
If a new abstraction is introduced, it should clearly reduce complexity rather than move it around

Questions?

If you have questions, ideas, or half-formed insights, you are warmly welcome here.

Please feel free to open an issue, join the community, or simply reach out:

Discord
Feishu/WeChat
Email: Xubin Ren (@Re-bin) — xubinrencs@gmail.com

Thank you for spending your time and care on nanobot. We would love for more people to participate in this community, and we genuinely welcome contributions of all sizes.

4.1 KiB Raw Blame History