Gentleman-Programming/release

何时使用

在准备、发布或验证 gentle-pi 版本时使用此技能。

硬性规则

• 禁止从本地机器向 npm 发布 gentle-pi。
• npm 发布必须通过 GitHub Actions 工作流 .github/workflows/publish.yml 进行，以确保出处证明、环境安全和注册凭据由 GitHub 控制。
• 从受保护的默认 main 分支调度受信任的工作流定义，切勿从发布标签。其唯一的调用者输入是精确的带注释版本标签。
• 为发布提交使用干净的工作树。不要打包无关的本地文件或临时工件。
• 评审结果仅供参考。发布交付遵循常规仓库策略，不得被 RDD 阻止、授权或重写。
• 切勿从本地 HEAD 推断发布标签目标；使用新获取的 origin/main 提交和仓库正常的发布安全措施。
• 切勿跳过包验证。发布工作流会再次运行验证，但本地验证在打标签前应仍能通过。

发布流程

1. 检查状态

   git status --short
   git fetch origin main --tags
   git log --oneline --decorate --max-count=5 origin/main
   

2. 准备发布提交

   • 仅应用预期的更改。
   • 将 package.json 中的版本升级到下一个 semver 版本。
   • 除非依赖项解析实际发生变化，否则保持锁文件不变。

3. 本地验证

   pnpm test
   node scripts/verify-package-files.mjs
   npm pack --dry-run
   

   npm pack --dry-run 会验证包内容和生命周期脚本，而不会进入发布路径。

4. 提交并推送

   git add <预期文件>
   git commit -m "<type(scope): release-ready change>"
   git push origin HEAD:main
   git fetch origin main --tags
   

5. 创建并验证精确版本标签

   version="$(node -p "require('./package.json').version")"
   tag="v${version}"
   release_sha="$(git rev-parse 'origin/main^{commit}')"
   
   test "$(git rev-parse 'HEAD^{commit}')" = "${release_sha}"
   test -z "$(git ls-remote --tags origin "refs/tags/${tag}")"
   
   git tag -a "${tag}" "${release_sha}" -m "gentle-pi ${tag}"
   test "$(git rev-parse "${tag}^{commit}")" = "${release_sha}"
   
   git fetch origin main
   test "$(git rev-parse 'origin/main^{commit}')" = "${release_sha}"
   git push origin "refs/tags/${tag}"
   
   git fetch --no-tags origin "refs/tags/${tag}"
   test "$(git rev-parse 'FETCH_HEAD^{commit}')" = "${release_sha}"
   
   gh release create "${tag}" \
     --repo Gentleman-Programming/gentle-pi \
     --verify-tag \
     --title "gentle-pi ${tag}" \
     --notes "<发布说明>"
   

   不要重新打标签或覆盖已存在的版本。标签目标来自新获取的不可变的 origin/main 提交，而不是来自本地分支。

6. 通过 GitHub Actions 发布 npm

   version="$(node -p "require('./package.json').version")"
   tag="v${version}"
   gh workflow run publish.yml \
     --repo Gentleman-Programming/gentle-pi \
     --ref main \
     -f tag="${tag}"
   

   工作流定义始终来自受保护的默认 main 分支。它仅接受一个精确的 vSemVer 标签，获取远程带注释标签和当前的远程 main，并要求剥离的标签提交、调度/main 工作流提交、检出和 package.json 版本匹配。它会在 npm 发布前立即重新查询远程标签和 main，内部派生 dist-tag，并使用带有出处证明的可信 OIDC。

   监视运行，如果失败则终止发布：

   gh run list --repo Gentleman-Programming/gentle-pi --workflow publish.yml --limit 3
   gh run watch <run-id> --repo Gentleman-Programming/gentle-pi --exit-status
   

7. 验证 npm

   npm view gentle-pi@<version> version --registry=https://registry.npmjs.org/
   npm dist-tag ls gentle-pi --registry=https://registry.npmjs.org/
   

失败处理

• 发布失败通过常规仓库策略处理。不会重新打开或更改评审线索。

• 切勿尝试或重试本地 npm publish。仅当同一标签仍指向当前远程 main 且失败仅为发布相关时，才从受信任的 main 重新调度。

• 如果远程 main 已经推进，不要移动或重新创建现有标签。准备一个新的发布提交/版本并创建一个新的带注释版本标签。

• 如果工作流失败，使用以下命令检查日志：

  gh run view <run-id> --repo Gentleman-Programming/gentle-pi --log
  

• 如果工作流成功但 npm 验证短暂滞后，请先检查确切版本 (npm view gentle-pi@<version> version)，然后再假设发布失败。

输出约定

报告：

• 推送到 main 的提交 SHA。
• 精确版本标签及其剥离的提交 SHA。
• GitHub 发布 URL。
• 发布工作流运行 URL 及其结论。
• npm 确切版本以及工作流派生的 dist-tag（latest、beta 或 next）。
• 任何剩余的后续操作或警告。