version-bump

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Version Bump & Release Workflow

版本升级与发布工作流

IMPORTANT: Plan and write detailed release notes before starting.

CRITICAL: Commit EVERYTHING (including build artifacts). At the end of this workflow, NOTHING should be left uncommitted or unpushed. Run

git status

at the end to verify.

重要提示： 开始前请规划并撰写详细的发布说明。

关键要求： 提交所有内容（包括构建产物）。工作流结束时，不得有任何未提交或未推送的内容。最后运行

git status

进行验证。

Preparation

准备工作

Analyze: Determine if the change is PATCH (bug fixes), MINOR (features), or MAJOR (breaking).
Environment: Identify repository owner/name from
```
git remote -v
```
.
Paths — every file that carries the version string:
- ```
package.json
```
  — the npm/npx-published version (
```
npx claude-mem@X.Y.Z
```
  resolves from this)
- ```
plugin/package.json
```
  — bundled plugin runtime deps
- ```
.claude-plugin/marketplace.json
```
  — version inside
```
plugins[0].version
```
- ```
.claude-plugin/plugin.json
```
  — top-level Claude-plugin manifest
- ```
plugin/.claude-plugin/plugin.json
```
  — bundled Claude-plugin manifest
- ```
.codex-plugin/plugin.json
```
  — Codex-plugin manifest
- ```
plugin/.codex-plugin/plugin.json
```
  — bundled Codex-plugin manifest
- ```
openclaw/openclaw.plugin.json
```
  — OpenClaw plugin manifest
Verify coverage before editing:
```
git grep -l "\"version\": \"<OLD>\""
```
should list all eight. If a new manifest has been added since this doc was last updated, update this list.

分析：判断本次变更属于PATCH（补丁，修复bug）、MINOR（小版本，新增功能）还是MAJOR（大版本，破坏性变更）。
环境：通过
```
git remote -v
```
确认仓库所有者/名称。
路径 — 所有包含版本号的文件：
- ```
package.json
```
  — npm/npx发布版本（
```
npx claude-mem@X.Y.Z
```
  从此文件解析版本）
- ```
plugin/package.json
```
  — 插件捆绑运行时依赖
- ```
.claude-plugin/marketplace.json
```
  —
```
plugins[0].version
```
  中的版本号
- ```
.claude-plugin/plugin.json
```
  — 顶层Claude插件清单
- ```
plugin/.claude-plugin/plugin.json
```
  — 捆绑后的Claude插件清单
- ```
.codex-plugin/plugin.json
```
  — Codex插件清单
- ```
plugin/.codex-plugin/plugin.json
```
  — 捆绑后的Codex插件清单
- ```
openclaw/openclaw.plugin.json
```
  — OpenClaw插件清单
编辑前请验证覆盖范围：运行
```
git grep -l "\"version\": \"<OLD>\""
```
应列出上述8个文件。如果自本文档上次更新后新增了新的清单文件，请更新此列表。

Workflow

工作流步骤

Update: Increment the version string in every path above. Do NOT touch
```
CHANGELOG.md
```
— it's regenerated.

Verify:

git grep -n "\"version\": \"<NEW>\""

— confirm all eight files match.

git grep -n "\"version\": \"<OLD>\""

— should return zero hits.

Build and sync:
```
npm run build-and-sync
```
to regenerate artifacts, sync the local marketplace copy, restart the worker, and clear the queue. Do not use plain
```
npm run build
```
for release validation because it can leave the local marketplace/worker out of sync.

Commit:

git add -A && git commit -m "chore: bump version to X.Y.Z"

Tag:
```
git tag -a vX.Y.Z -m "Version X.Y.Z"
```
.

Push:

git push origin main && git push origin vX.Y.Z

Publish to npm — HAND OFF TO HUMAN. The human maintainer raised npm security, so publishing now requires credentials/2FA only they can provide. The agent MUST NOT run
```
npm publish
```
(or
```
np
```
/
```
npm run release:*
```
, which also publish) itself. Hand off NPM publishing to the human now: stop and tell them the version is committed, tagged, and pushed, and that they must publish to npm to make
```
npx claude-mem@X.Y.Z
```
resolve. Give them the command:
bash
```
npm publish   # run by the HUMAN — the prepublishOnly script rebuilds the package
```
Wait for the human to confirm they published, then verify it landed:
bash
```
npm view claude-mem@X.Y.Z version   # should print X.Y.Z
```
If the publish build touched local artifacts, run
```
npm run build-and-sync
```
again afterward.

GitHub release:

gh release create vX.Y.Z --title "vX.Y.Z" --notes "RELEASE_NOTES"

Changelog: Regenerate via the project's changelog script:
bash
```
npm run changelog:generate
```
(Runs
```
node scripts/generate-changelog.js
```
, which pulls releases from the GitHub API and rewrites
```
CHANGELOG.md
```
.)
Sync changelog: Commit and push the updated
```
CHANGELOG.md
```
.
Notify: Run the Discord notification from
```
~/Scripts/claude-mem/
```
, where the
```
.env
```
with Discord webhook details lives:
bash
```
cd ~/Scripts/claude-mem/ && npm run discord:notify vX.Y.Z
```
Do this even when the release worktree does not have a local
```
.env
```
.
Finalize:
```
git status
```
— working tree must be clean.

更新版本：在上述所有路径中递增版本号。请勿修改
```
CHANGELOG.md
```
— 它会自动重新生成。
验证版本：运行
```
git grep -n "\"version\": \"<NEW>\""
```
— 确认所有8个文件的版本号一致。运行
```
git grep -n "\"version\": \"<OLD>\""
```
— 应返回零匹配结果。
构建与同步：运行
```
npm run build-and-sync
```
重新生成产物、同步本地市场副本、重启工作进程并清除队列。请勿使用普通的
```
npm run build
```
进行发布验证，因为它可能导致本地市场/工作进程不同步。

提交变更：运行

git add -A && git commit -m "chore: bump version to X.Y.Z"

。

打标签：运行
```
git tag -a vX.Y.Z -m "Version X.Y.Z"
```
。

推送代码：运行

git push origin main && git push origin vX.Y.Z

。

NPM发布 — 交由人类完成。人类维护者提出了npm安全要求，因此发布现在需要只有他们能提供的凭据/双因素认证。Agent不得自行运行
```
npm publish
```
（或
```
np
```
/
```
npm run release:*
```
等会触发发布的命令）。现在将NPM发布工作交给人类： 停止操作并告知他们版本已提交、打标签并推送，他们必须发布到npm以确保
```
npx claude-mem@X.Y.Z
```
可正常解析。提供命令：
bash
```
npm publish   # 由人类执行 — prepublishOnly脚本会重新构建包
```
等待人类确认发布完成，然后验证发布结果：
bash
```
npm view claude-mem@X.Y.Z version   # 应输出X.Y.Z
```
如果发布构建修改了本地产物，之后请再次运行
```
npm run build-and-sync
```
。

GitHub发布：运行

gh release create vX.Y.Z --title "vX.Y.Z" --notes "RELEASE_NOTES"

。

生成变更日志：通过项目的变更日志脚本重新生成：
bash
```
npm run changelog:generate
```
（运行
```
node scripts/generate-changelog.js
```
，该脚本从GitHub API拉取发布信息并重写
```
CHANGELOG.md
```
。）
同步变更日志：提交并推送更新后的
```
CHANGELOG.md
```
。
发送通知：从
```
~/Scripts/claude-mem/
```
运行Discord通知脚本，该目录下存放着包含Discord webhook信息的
```
.env
```
文件：
bash
```
cd ~/Scripts/claude-mem/ && npm run discord:notify vX.Y.Z
```
即使发布工作目录中没有本地
```
.env
```
文件，也要执行此步骤。
最终验证：运行
```
git status
```
— 工作树必须干净无变更。

Checklist

检查清单

All eight config files have matching versions
```
git grep
```
for old version returns zero hits
```
npm run build-and-sync
```
succeeded
Git tag created and pushed
NPM publishing handed off to the human (agent does NOT run
```
npm publish
```
— human raised security); once they publish,
```
npm view claude-mem@X.Y.Z version
```
confirms it (so
```
npx claude-mem@X.Y.Z
```
resolves)
GitHub release created with notes
```
CHANGELOG.md
```
updated and pushed
Discord notification run from
```
~/Scripts/claude-mem/
```
```
git status
```
shows clean tree

所有8个配置文件的版本号一致
搜索旧版本号的
```
git grep
```
命令返回零匹配
```
npm run build-and-sync
```
执行成功
Git标签已创建并推送
NPM发布已交由人类完成（Agent不得运行
```
npm publish
```
— 出于安全要求由人类执行）；发布完成后，
```
npm view claude-mem@X.Y.Z version
```
可验证版本（确保
```
npx claude-mem@X.Y.Z
```
可正常解析）
已创建带发布说明的GitHub发布
```
CHANGELOG.md
```
已更新并推送
已从
```
~/Scripts/claude-mem/
```
发送Discord通知
```
git status
```
显示工作树干净