From 5a220959afd7e497cb9e8a2bbfc9031433bc96a7 Mon Sep 17 00:00:00 2001
From: chengyongru <2755839590@qq.com>
Date: Sun, 15 Mar 2026 02:30:09 +0800
Subject: [PATCH] docs: add branching strategy and CONTRIBUTING guide

- Add CONTRIBUTING.md with detailed contribution guidelines
- Add branching strategy section to README.md explaining main/nightly branches
- Include maintainer information and development setup instructions
---
 CONTRIBUTING.md | 91 +++++++++++++++++++++++++++++++++++++++++++++++++
 README.md       |  9 +++++
 2 files changed, 100 insertions(+)
 create mode 100644 CONTRIBUTING.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..626c8bb
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,91 @@
+# Contributing to nanobot
+
+Thank you for your interest in contributing! This guide will help you get started.
+
+## Maintainers
+
+| Maintainer | Focus |
+|------------|-------|
+| [@re-bin](https://github.com/re-bin) | Project lead, `main` branch |
+| [@chengyongru](https://github.com/chengyongru) | `nightly` branch, experimental features |
+
+## Branching Strategy
+
+nanobot uses a two-branch model to balance stability and innovation:
+
+| 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's easier to cherry-pick stable changes to `main` than to revert unstable changes.
+
+### 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
+
+```bash
+# 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
+
+- 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"`
+
+## Questions?
+
+Feel free to open an [issue](https://github.com/HKUDS/nanobot/issues) or join our community:
+
+- [Discord](https://discord.gg/MnCvHqpUGB)
+- [Feishu/WeChat](./COMMUNICATION.md)
diff --git a/README.md b/README.md
index bc27255..424d290 100644
--- a/README.md
+++ b/README.md
@@ -1410,6 +1410,15 @@ nanobot/
 
 PRs welcome! The codebase is intentionally small and readable. 🤗
 
+### Branching Strategy
+
+| Branch | Purpose |
+|--------|---------|
+| `main` | Stable releases — bug fixes and minor improvements |
+| `nightly` | Experimental features — new features and breaking changes |
+
+**Unsure which branch to target?** See [CONTRIBUTING.md](./CONTRIBUTING.md) for details.
+
 **Roadmap** — Pick an item and [open a PR](https://github.com/HKUDS/nanobot/pulls)!
 
 - [ ] **Multi-modal** — See and hear (images, voice, video)