release

从 fromargs 发布

这是一个 skillz-that-grillz 仓库本地技能。它位于 .agents/skills/release/，并通过 .claude/skills/ 符号链接供 Claude Code 使用。metadata.internal: true 会使它不会被 npx skills add 发现。不要将它移入已发布的 skills/ 目录树。

推送标签后，只需一次审批即可发布到 PyPI，而 PyPI 永远不会接受同一版本两次。请将标签推送和审批视为不可撤销操作。

发布约定

• packages/fromargs/CHANGELOG.md 是发布说明的唯一来源。just fromargs-release-notes <version> 会输出一个章节；如果该章节缺失或为空，则会失败。
• .github/workflows/publish-fromargs.yml 会在推送 fromargs-v* 标签时运行。其构建任务要求标签对应的提交位于 main 上，且标签版本与 packages/fromargs/pyproject.toml 中的版本一致。
• publish 任务会等待 pypi 环境审批，然后使用受信任发布上传。
• github-release 任务会使用 --latest=false 创建 GitHub 发布。如果标签在构建后发生变动，则该任务会失败。
• wedge 包和 cheese-cave 示例锁文件中包含 fromargs 源码，因此更改版本后需要重新构建。

1. 发布前检查

1. 切换到 main，使用 --ff-only 拉取，并确认工作区干净。
2. 阅读 packages/fromargs/CHANGELOG.md 的 ## [Unreleased] 章节。如果该章节为空，则停止。
3. 选择版本。用户指定版本时使用该版本。否则，对于包含 Breaking 条目的 0.x 发布，建议下一个次版本；对于其他更改，建议下一个补丁版本。向用户确认建议的版本。
4. 如果标签 fromargs-v<version> 已存在于 origin 上，或 https://pypi.org/pypi/fromargs/<version>/json 返回 200，则停止。

2. 准备发布 PR

1. 创建分支 chore/fromargs-release-<version>。

2. 在 packages/fromargs/CHANGELOG.md 中，将 Unreleased 条目移至 ## [<version>] - <YYYY-MM-DD> 下，并使用今天的日期。保留空的 ## [Unreleased] 标题。

3. 更新 CHANGELOG 末尾的链接引用。[Unreleased] 比较 fromargs-v<version>...HEAD。添加 [<version>]，用于比较上一个标签与 fromargs-v<version>。

4. 在 packages/fromargs/pyproject.toml 中设置 version = "<version>"。

5. 次版本发生变化时，将 pyproject.toml 和 packages/wedge/pyproject.toml 中的 fromargs 范围设为 >=<major>.<minor>.0,<<major>.<next minor>。

6. 使用工作流 setup-uv 步骤中固定的 uv 版本重新锁定工作区，以确保锁文件的 revision 与 CI 兼容：

   uvx uv@<ci-uv-version> lock
   

7. 重新构建包含 fromargs 的制品：

   uv run --locked --project packages/wedge wedge lock --root packages/wedge/examples/skills
   uv run --locked --project packages/wedge wedge bundle skills/skillz
   

8. 运行 just fromargs-release-notes <version> 并阅读输出。输出必须包含完整的新章节。

9. 运行 uv build --package fromargs --no-sources --out-dir <temp dir> 和 uvx twine check <temp dir>/*。

10. 运行 just build。出现新的失败时停止。将任何失败与干净的 main 检出进行比较，然后再判定其为基线失败。

11. 按 chore(fromargs): release <version> 提交指定文件。推送分支并向 main 发起 PR。在 PR 正文中写入发布说明和合并后的步骤。

3. 合并

1. 等待所有 PR 检查通过。解决或回复所有评审讨论。
2. 获得用户明确批准后再合并，除非用户在本次会话中要求完成整个发布流程。
3. 使用 gh pr merge <n> --squash --match-head-commit <sha> 执行压缩合并。记录合并提交 SHA。
4. 如果合并日期与 CHANGELOG 日期不同，则在打标签前通过新 PR 修正日期。

4. 打标签并审批

1. 获取 main。确认合并提交位于 origin/main 上，且其中包含新版本和 CHANGELOG 章节。

2. 在合并提交上创建并推送附注标签：

   git tag -a fromargs-v<version> <merge-sha> -m "Release fromargs <version>"
   git push origin fromargs-v<version>
   

3. 找到该标签对应的 publish fromargs 运行。等待构建任务通过，且运行进入等待 pypi 环境审批的状态。

4. 只有在用户批准后才批准部署，除非用户在本次会话中要求完成整个发布流程：

   gh api repos/<owner>/<repo>/actions/runs/<run-id>/pending_deployments \
     -X POST -F "environment_ids[]=<pypi-env-id>" -f state=approved \
     -f comment="Approve fromargs <version>"
   

5. 验证

1. 观察运行直至完成。每个作业都必须成功。
2. 查看 https://pypi.org/pypi/fromargs/<version>/json。确认版本、依赖范围，以及一个 wheel 和一个 sdist。
3. 查看 gh release view fromargs-v<version>。确认它不是草稿，正文以 CHANGELOG 部分开头，并且已附上两个分发文件。
4. 确认仓库的最新发行版没有变化。

失败处理规则

• 绝不移动、删除或重新推送已发布的标签。修复问题需要使用新的补丁版本。
• 如果构建作业失败，则尚未进行上传。在 main 上修复原因；只有获得用户批准后，才能删除尚未发布的标签，然后重新打标签。
• 如果 PyPI 上已有该版本，但 github-release 作业失败，则只重新运行失败的作业：gh run rerun <run-id> --failed。
• 绝不批准标签未指向已审核的合并提交的运行的部署。

报告

报告 PR、合并提交、标签、工作流运行、PyPI URL 和 GitHub 发行版 URL。列出所有未运行的检查。