# 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