Skip to content

plugin-release.md

Latest commit

 

History

History
99 lines (68 loc) · 3.32 KB

plugin-release.md

File metadata and controls

99 lines (68 loc) · 3.32 KB
Raw

插件发版指南

本项目的发布说明优先面向中文网文作者：先说明这版对写书有什么帮助，再补维护者关心的 CLI、schema、测试和 CI 细节。

发版前审计

发布说明必须覆盖“上一个正式版本 tag 到本次发布提交”的全部变化，而不是只写最后一次提交。

发版前先确认版本边界：

git tag --list "v*" --sort=-v:refname
git log --oneline v上一版本..HEAD
git diff --stat v上一版本..HEAD

把变化分成四类：

  • 给作者看的变化：写章、审查、规划、查询、恢复、文档等用户能感受到的变化。
  • 兼容性：是否需要迁移旧书项目，是否改变现有 /webnovel-* 命令习惯。
  • 已知影响：跳过项、限制、需要注意的风险。
  • 给维护者：新增 CLI、schema、helper、测试、CI、内部重构。

发布说明来源

每个正式版本都必须有两份文档：

  • CHANGELOG.md：长期更新日志。
  • releases/vX.Y.Z.md：GitHub Release 正文的唯一来源。

README 只保留一句中文用户收益摘要，例如：

| **v6.2.0 (当前)** | 写章结果更清楚，失败后更好恢复 |

不要把 README 当完整 changelog。

版本同步

写好 CHANGELOG.md 和 releases/vX.Y.Z.md 后，再同步版本号和 README 摘要：

python -X utf8 webnovel-writer/scripts/sync_plugin_version.py --version X.Y.Z --release-notes "一句中文用户收益"

该命令会更新：

  • webnovel-writer/.claude-plugin/plugin.json
  • .claude-plugin/marketplace.json
  • README.md 版本徽章
  • README.md 当前版本行

本地校验

提交前至少运行：

python -X utf8 webnovel-writer/scripts/sync_plugin_version.py --check --expected-version X.Y.Z
python -X utf8 webnovel-writer/scripts/validate_release_notes.py --version X.Y.Z
python -X utf8 webnovel-writer/scripts/validate_plugin_package.py
git diff --check

涉及代码或提示词变化时，还要运行对应 pytest、行为评估或 smoke test，并把结果写进 releases/vX.Y.Z.md 的“验证”小节。

自动发版

  1. 确认本地校验通过。
  2. 提交并推送版本说明和版本元数据到 master。
  3. Plugin Release 工作流会自动：
    • 校验 plugin.json、marketplace.json、README 版本一致。
    • 校验 CHANGELOG.md 和 releases/vX.Y.Z.md 存在且覆盖上个 tag。
    • 校验插件包结构。
    • 创建并推送 vX.Y.Z tag。
    • 使用 releases/vX.Y.Z.md 创建 GitHub Release。

如果对应 tag 已存在，工作流不会重复打 tag；如果 GitHub Release 已存在，也会自动跳过。若之前只创建了 tag 但 Release 缺失，重跑工作流会补建 Release。

也可以在 Actions 页面手动选择 Plugin Release 兜底触发。手动运行时可以输入 version，也可以留空让工作流从 plugin.json 读取当前版本。

自动版本校验

Plugin Version Check 工作流会在 Push / PR 时自动检查：

  • 版本元数据一致。
  • README 版本徽章一致。
  • 当前版本有 release note。
  • CHANGELOG.md 包含当前版本。

触发文件：

  • .claude-plugin/marketplace.json
  • webnovel-writer/.claude-plugin/plugin.json
  • webnovel-writer/scripts/sync_plugin_version.py
  • webnovel-writer/scripts/validate_release_notes.py
  • README.md
  • CHANGELOG.md
  • releases/**