archived-MoviePilot-Plugins/docs/RELEASE_CHECKLIST.md

Release Checklist

发布前按这个顺序执行，避免漏包、错包或上传旧 ZIP。

如果你只想走一条完整命令，直接执行：

bash scripts/release-preflight.sh

它会先跑 repo-hygiene.sh，再跑 pre-release-check.sh。

如果你只想快速查维护/发布命令，不想通读整份清单，直接看：

• docs/MAINTENANCE_COMMANDS.md

1. 确认工作区

git status --short --branch

工作区应当干净。

2. 查看插件清单

bash scripts/package-plugin.sh --list

确认输出的插件和版本符合本次发布预期。

同时确认当前对外文档没有落后：

• README.md
• docs/INDEX.md
• docs/PLUGIN_INSTALL.md
• docs/AGENT_RESOURCE_OFFICER_EXTERNAL_AGENTS.md
• docs/AGENT_RESOURCE_OFFICER_REMOTE_DEPLOY.md

3. 执行完整检查

如果只改了 Skill，可以先跑轻量检查：

bash scripts/check-skills.sh

最终发布前仍然执行完整检查：

bash scripts/release-preflight.sh

这个命令会先跑 repo-hygiene.sh，再执行 pre-release-check.sh；后者会同步 plugins/ 和 plugins.v2/，检查元数据、Skill helper、ZIP 内容，并重新生成插件 ZIP、Skill ZIP、SHA256SUMS.txt 和 MANIFEST.json。

其中也会自动执行：

python3 scripts/check-doc-current-state.py

用来校验当前状态文档中的插件版本、helper 版本和 release URL 没有落后于代码。

如果本机已经跑着可访问的 MoviePilot，并且 ~/.config/agent-resource-officer/config 已配置 ARO_BASE_URL / ARO_API_KEY，建议追加一次真实链路检查：

RUN_AGENT_RESOURCE_OFFICER_LIVE_SMOKE=1 bash scripts/pre-release-check.sh

4. 上传 ZIP

Release 附件上传 dist/ 下的插件 ZIP、dist/skills/ 下的 Skill ZIP。创建 Draft Release 时，脚本会把校验文件改名为唯一附件名，避免 GitHub Release 附件重名：

• PLUGIN_SHA256SUMS.txt
• PLUGIN_MANIFEST.json
• SKILL_SHA256SUMS.txt
• SKILL_MANIFEST.json

本地核对命令：

ls -1 dist/*.zip
ls -1 dist/skills/*.zip
cat dist/SHA256SUMS.txt
cat dist/MANIFEST.json
cat dist/skills/SHA256SUMS.txt
cat dist/skills/MANIFEST.json
bash scripts/verify-release-assets.sh
bash scripts/verify-dist.sh
bash scripts/verify-skill-dist.sh
bash scripts/print-release-summary.sh
bash scripts/print-skill-release-summary.sh

不要上传历史旧包。pre-release-check.sh 会在打包前清理旧 ZIP。

5. 远端确认

推送后确认 GitHub Actions 通过：

gh run list --limit 3

Release Preflight workflow 通过后会在该 run 的 Artifacts 区域生成 moviepilot-release-assets-<commit>，里面包含本次插件 ZIP、Skill ZIP、SHA256SUMS.txt 和 MANIFEST.json。Draft Release 附件中的校验文件会使用 PLUGIN_ / SKILL_ 前缀避免重名。

如需在本地下载并校验最近一次成功 Release Preflight artifact：

bash scripts/verify-release-preflight-artifact.sh

也可以指定 run id：

bash scripts/verify-release-preflight-artifact.sh 25017759143

如果已经从 GitHub Release 页面下载了全部附件，也可以直接校验下载目录：

bash scripts/verify-release-download.sh <tag>
bash scripts/verify-release-assets.sh /path/to/release-assets

如果 Draft Release 已存在，需要用当前 dist/ 重新覆盖 notes 和附件：

bash scripts/update-draft-release-assets.sh <tag> --skip-check

也可以在 GitHub 页面手动运行：Actions -> Release Preflight -> Run workflow。

6. 创建 Draft Release

先 dry-run，确认附件和说明能生成：

bash scripts/create-draft-release.sh <tag> --dry-run

确认无误后创建 GitHub Draft Release：

bash scripts/create-draft-release.sh <tag>

也可以在 GitHub Actions 手动触发：

gh workflow run draft-release.yml -f tag=<tag> -f dry_run=true

dry-run 通过后会生成 moviepilot-release-assets-<tag>-<commit> artifact，可先下载核对。确认无误后，再用 dry_run=false 创建 Draft Release。

7. 发布正式 Release

Draft Release 核对无误后发布正式 Release：

gh release edit <tag> --draft=false --latest --target main

发布后确认状态、tag 和公开附件：

gh release view <tag> --json tagName,isDraft,isPrerelease,url,publishedAt,targetCommitish
git ls-remote --tags origin "refs/tags/<tag>"
bash scripts/verify-release-download.sh <tag>

正式发布后，isDraft 应为 false，公开下载校验必须通过。

8. 发布后清理

发布完成后，顺手清理本地过期的远端引用，并检查是否有已经不再需要的发布分支：

git fetch --prune origin
git branch -r
python3 scripts/audit-remote-branches.py

如果远端已经收干净，但本地还留着大量历史分支，可先看 dry-run：

python3 scripts/archive-local-branches.py

确认无误后再执行：

python3 scripts/archive-local-branches.py --apply

这个脚本会先把本地历史分支转成 archive/<branch> 本地 tag，再删除分支名。

如果只是想一条命令快速看当前仓库分支卫生状态，可以执行：

bash scripts/repo-hygiene.sh

注意：

• 远端分支如果是通过 squash merge 合并，git merge-base --is-ancestor 不能直接作为删分支依据。
• 删除前先确认该分支没有关联 PR，且不再需要保留为历史参考。
• 如果只是本地看到“远端分支还在”，先 fetch --prune，不要直接假设远端没清理。