swarm-zap/scripts/openclaw-upstream-workflow.md

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

cd external/openclaw-upstream
git fetch --all --prune
git checkout main
git pull --ff-only
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. Push branch and open PR.

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:

scripts/openclaw-update-safe.sh

• After runtime update, re-sync upstream clone before new changes:

cd external/openclaw-upstream && git fetch --all --prune && git checkout main && git pull --ff-only

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