Publish Repo
End-to-end release workflow for npm packages. Handles version bump, docs, build, test, publish, push, and global install.
Prerequisites
- Must be in a directory with
package.json - Must have npm publish access (already logged in)
- Git working tree should be clean or have only the changes to release
Steps
0. Verify state
git branch
git status
Confirm you're on the correct branch (usually master or main). If not, ask before proceeding.
1. Determine version bump
Check the current version from package.json. Determine the bump type:
- If the user specifies a version (e.g., "bump to 0.12.0"), use that exactly.
- If the user says "patch", "minor", or "major", bump accordingly.
- If unspecified, infer from the changes in this session:
- Bug fix or small improvement: patch (0.11.1 -> 0.11.2)
- New feature or capability: minor (0.11.1 -> 0.12.0)
- Breaking change: major (0.11.1 -> 1.0.0)
- Confirm the version with the user before proceeding if ambiguous.
2. Bump version in ALL manifests
NEVER use npm version — it only bumps package.json and package-lock.json. Always bump manually with Edit to catch every manifest.
Search for the old version string across the repo:
grep -rn '"version".*OLD_VERSION' --include='*.json' . | grep -v node_modules | grep -v package-lock
Typical files to bump (edit each one):
package.json(root)- Any nested
package.jsonfiles (extensions/, plugins/) - Any
*.plugin.jsonoropenclaw.plugin.jsonmanifests - MCP server version strings in source code
After bumping all manifests, run npm install to sync package-lock.json to the new version.
Verify all manifests match after bumping — grep again and confirm zero hits for the old version (excluding package-lock.json and node_modules).
Update ALL of them. Do NOT leave any behind. This has caused version desync bugs before.
3. Update CHANGELOG.md
Add a new section at the top, after the # Changelog heading:
## X.Y.Z (YYYY-MM-DD)
### Fixed / Added / Changed
- **Short title.** Description of the change.
Use today's date. Categorize entries as Fixed, Added, or Changed. Keep descriptions concise but specific.
4. Update README.md
Add a "What's new in vX.Y.Z" section if the README has that pattern. Keep it to 1-3 bullet points. Do not rewrite existing sections.
5. Update other relevant docs
Check for:
- Plugin/extension READMEs that reference the changed functionality
- Integration guides affected by the changes
- Any doc that references the old behavior
Only update docs that are actually affected. Do not touch unrelated files.
6. Build
npm run build
Must succeed before proceeding.
7. Test
npx vitest run
Or whatever the test command is (npm test, npx jest, etc.). ALL tests must pass. If a test fails due to version sync, fix it. If a test fails for other reasons, stop and report.
8. Commit
Stage only the changed files (not git add -A). Write a commit message:
chore: bump to vX.Y.Z, update changelog and readme
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
9. Publish to npm
npm publish
Wait for confirmation. If it fails (auth, version conflict), report and stop.
10. Tag and push
git tag vX.Y.Z
git push origin <branch>
git push origin vX.Y.Z
11. Install globally (if applicable)
If the package is a CLI tool (has a bin field in package.json):
npm install -g <package-name>@X.Y.Z
Verify:
<cli-command> --version
12. Close related issues/PRs
If any commits reference Closes #N or Fixes #N, verify the issues/PRs were closed. If not, close them manually with a comment.
Rules
- Never publish without passing tests.
- NEVER use
npm versionto bump. It misses plugin manifests and causes version desync. Always edit each file manually. - Never skip the version bump in any manifest. Grep to find them all.
- After bumping, verify with grep that no manifest still has the old version.
- If
package-lock.jsonis stale, runnpm installto regenerate it before committing. - Do not amend previous commits. Always create new commits.
- Report what was published at the end: package name, version, npm URL, tag.