wangjunxiao/nanoclaw
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add branch and fork maintenance guidelines

Browse Source 
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
gavrielc
2026-03-28 14:48:34 +03:00
parent 37aee02b46
commit 8bb8e036e4
1 changed files with 79 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

79
docs/BRANCH-FORK-MAINTENANCE.md Normal file
View File

@@ -0,0 +1,79 @@
# Branch & Fork Maintenance Guidelines
## Structure
**`qwibitai/nanoclaw`** (upstream) — core engine with skill definitions (`.claude/skills/`). No channel code on `main`.
**Channel forks** (`nanoclaw-whatsapp`, `nanoclaw-telegram`, `nanoclaw-slack`, etc.) — each fork = upstream + one channel's code applied. Users clone upstream, then merge a fork into their clone to add a channel.
**`skill/*` and `feat/*` branches on upstream** — add features unrelated to channels (e.g. `skill/compact`, `skill/apple-container`). Users merge these into their clone to add capabilities. Channel-specific skill branches that duplicate the forks (e.g. `skill/whatsapp`, `skill/telegram`) are legacy.
## How users add capabilities
```
user clones upstream main
├── merges nanoclaw-whatsapp fork → adds WhatsApp
├── merges skill/compact branch → adds /compact command
└── merges skill/apple-container → switches to Apple Container
```
## Merge directions
```
upstream main ──→ channel forks (forward merge to keep forks caught up)
upstream main ──→ skill branches (forward merge to keep branches caught up)
```
Forks and skill branches carry applied code changes. Users merge them into their own clones/forks to add capabilities. They are never merged back into upstream `main`.
## Forward merge procedure
```bash
# In your local nanoclaw checkout
git checkout main && git pull
# For a fork:
git fetch nanoclaw-whatsapp
git checkout -B whatsapp-merge nanoclaw-whatsapp/main
git merge main
# Resolve conflicts (see below)
git push nanoclaw-whatsapp HEAD:main
git checkout main && git branch -D whatsapp-merge
# For a skill branch:
git checkout -B skill/compact origin/skill/compact
git merge main
# Resolve conflicts (see below)
git push origin skill/compact
git checkout main && git branch -D skill/compact
```
## Conflict resolution
The same files conflict every time:
| File | Resolution |
|------|------------|
| `package.json` | Take main's version + keep fork/branch-specific deps |
| `package-lock.json` | `git checkout main -- package-lock.json && npm install` |
| `.env.example` | Combine: main's entries + fork/branch-specific entries |
| `repo-tokens/badge.svg` | Take main's version (auto-generated) |
Source code merges cleanly because forks/branches primarily add files rather than modifying shared code.
## When to merge forward
After any main change that touches shared files (`package.json`, `src/index.ts`, `CLAUDE.md`, etc.). Small frequent merges = trivial conflicts. Large infrequent merges = painful.
## Fork setup
When creating a new channel fork:
1. Fork `nanoclaw` to `nanoclaw-{channel}`
2. Remove upstream-only workflows: `bump-version.yml`, `update-tokens.yml`
3. Add channel code, deps, env vars
4. Forward-merge main immediately to establish a clean baseline
## Dependencies
Forks and branches add their own deps on top of upstream's. When upstream adds or removes a dependency, verify that forks/branches still build after the next forward merge — transitive dependency changes can break downstream code.