mirror/nanobot
1
0
Fork 0
mirror of https://github.com/HKUDS/nanobot.git synced 2026-06-13 22:34:06 +00:00
Code Issues Packages Projects Releases Wiki Activity
nanobot/CONTRIBUTING.md
chengyongru 6e6470daa0 docs: remove nightly branch guidance
2026-06-08 16:03:24 +08:00

4.8 KiB
Raw Blame History

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

Maintainers are community stewards who help review, organize, and maintain the project. The list below describes each maintainer's current open-source project responsibilities.

Maintainer Role
@re-bin Project lead; reviews community PRs and handles merges
@chengyongru Reviews community PRs and may approve them; merges are handled by the project lead

Contribution Flow

What Should I Open a PR For?

PRs are welcome for:

  • New features or functionality
  • Bug fixes with no behavior changes
  • Documentation improvements
  • Minor tweaks that don't affect functionality
  • Refactoring that is clearly scoped and easy to review
  • Changes to APIs or configuration, when the impact is documented

For riskier or larger changes, please open an issue or draft PR early so the shape of the work can be discussed before the implementation grows too large.

Starting Work

Before making changes, sync your local checkout and create a topic branch.

git fetch upstream
git switch main
git pull --ff-only upstream main
git switch -c your-topic-branch

Use your primary HKUDS/nanobot remote in place of upstream if your checkout uses a different remote name.

Keep unrelated local changes out of the topic branch. If your checkout already has work in progress, use a separate worktree or finish that work before starting a new branch.

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 — optional. The existing tree predates `ruff format`,
# so running it broadly produces large unrelated diffs.
# Do not mix mechanical formatting churn into a functional PR.
# Use formatting only for the exact code your change intentionally touches.
ruff format <files-you-changed>

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
  • Do not mix mechanical formatting, line wrapping, import sorting, or quote churn into a feature or bugfix PR. If formatting cleanup is needed, make it a separate formatting-only PR.
  • If a new abstraction is introduced, it should clearly reduce complexity rather than move it around

Modifying CI Workflows

If your PR touches .github/workflows/, please keep the CI within GitHub Actions' free tier:

  • Use only standard GitHub-hosted runners (ubuntu-latest, windows-latest)
  • Avoid macOS runners, larger runners (*-cores, *-xlarge, *-gpu), and self-hosted runners
  • Avoid uploading large artifacts or using long retention
  • Avoid paid Marketplace actions

If your change genuinely needs to step outside this, please call it out explicitly in the PR description so it can be discussed before merge.

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:

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.