94 lines
2.1 KiB
Markdown
94 lines
2.1 KiB
Markdown
# OpenClaw Upstream Workflow
|
|
|
|
Use this whenever modifying OpenClaw itself.
|
|
|
|
## Source of truth
|
|
|
|
- Upstream working clone: `external/openclaw-upstream/`
|
|
- Install path (`~/.npm-global/lib/node_modules/openclaw/dist`) is runtime output, not long-term source.
|
|
|
|
## Standard flow
|
|
|
|
Quick preflight helper (recommended):
|
|
|
|
```bash
|
|
scripts/openclaw-upstream-preflight.sh fix/<short-topic>
|
|
```
|
|
|
|
Equivalent manual flow:
|
|
|
|
```bash
|
|
cd external/openclaw-upstream
|
|
git fetch --all --prune
|
|
git checkout main
|
|
git pull --rebase
|
|
git checkout -b fix/<short-topic>
|
|
```
|
|
|
|
Then:
|
|
1. Implement in `src/` (and docs/tests as needed).
|
|
2. Run targeted tests first; run broader suite if change touches shared paths.
|
|
3. Commit with Conventional Commit format.
|
|
4. Rebase onto latest `main` before push/PR:
|
|
- `git fetch origin && git rebase origin/main`
|
|
5. Push branch and open PR.
|
|
|
|
## Merge policy
|
|
|
|
- Preferred PR strategy: **Rebase and merge**
|
|
- Avoid merge commits unless explicitly required for a special case
|
|
|
|
## Post-merge branch cleanup (required)
|
|
|
|
After PR merge, delete the branch on both remote and local:
|
|
|
|
```bash
|
|
# from repo root
|
|
|
|
git checkout main
|
|
git pull --rebase
|
|
|
|
# delete remote branch
|
|
|
|
git push origin --delete <branch-name>
|
|
|
|
# delete local branch
|
|
|
|
git branch -d <branch-name>
|
|
```
|
|
|
|
If branch was not merged cleanly and Git blocks deletion, inspect first; only then force-delete local branch with:
|
|
|
|
```bash
|
|
git branch -D <branch-name>
|
|
```
|
|
|
|
## Branch naming
|
|
|
|
- `fix/...` for bugfixes
|
|
- `feat/...` for new behavior
|
|
- `chore/...` for maintenance
|
|
- keep names short and specific (`fix/tui-hide-internal-runtime-context`)
|
|
|
|
## Update hygiene
|
|
|
|
- Check runtime version: `openclaw update status`
|
|
- If local compatibility patch exists, update with:
|
|
|
|
```bash
|
|
scripts/openclaw-update-safe.sh
|
|
```
|
|
|
|
- After runtime update, re-sync upstream clone before new changes:
|
|
|
|
```bash
|
|
cd external/openclaw-upstream && git fetch --all --prune && git checkout main && git pull --rebase
|
|
```
|
|
|
|
## Emergency dist hotfix policy
|
|
|
|
If a dist-file hotfix is unavoidable:
|
|
- keep it scripted (`scripts/...`), idempotent, and reversible
|
|
- document it (`patches/.../README.md`)
|
|
- land the proper upstream source fix and PR as soon as possible
|