发布检查清单

English

准备 tag release 时使用这份清单。对于 v0.2.0，预期行为是：release tag 通过 GitHub Actions release workflow 发布 GitHub Release 和 GHCR container images。 PyPI 发布在 PyPI project 和 trusted publishing 配好之前默认关住。

维护者明确批准 release 之前，不要创建或推送 release tag。

发布前检查

• 确认工作树干净：git status --short --branch。
• 检查 release 状态前先抓取 tags：git fetch --tags origin。
• 确认目标 tag 本地和远端都不存在： git tag --list v0.2.0 和 git ls-remote --tags origin 'refs/tags/v0.2.0'。
• 确认 pyproject.toml、src/codex_quota_monitor/version.py、default.nix、 CHANGELOG.md 和公开文档里的版本一致。
• 确认将要打 tag 的 commit 上 GitHub Actions CI 为绿色。
• 确认 Pages workflow 在当前 main commit 上为绿色，并且 gh-pages 分支包含 该 commit 对应的已生成 HTML 站点。
• 确认 GHCR 还没有目标版本。
• 确认 pinned Docker base image digest 对这次 release 仍然足够新。
• 如果这次 release 改了 API、metrics、history、benchmark、日志、网络请求或部署行为， 复查 安全自审计 和 威胁模型 并同步更新。
• 如果这次要发布 PyPI，先按 PyPI trusted publishing 为 owner xsyxnx、repository codex-quota-monitor、workflow release.yml、environment pypi、project name codex-quota-monitor 配好 PyPI trusted publishing，再在推 tag 前设置 repository variable PYPI_PUBLISH_ENABLED=true。

本地验证

打 tag 前在仓库根目录运行：

nix develop -c python3 -m unittest discover -s tests -v
nix develop -c python3 -m build
nix build .#codex-quota-monitor --no-link
nix run .#codex-quota-monitor -- --help
nix run .#codex-quota-monitor -- --version
nix run .#codex-quota-monitor -- init --mode user >/tmp/cqm-init.txt
nix run .#codex-quota-monitor -- print-config --state-db off
printf 'state_db = "off"\ndisplay_timezone = "UTC"\n' >/tmp/cqm-config.toml
nix run .#codex-quota-monitor -- print-config --config /tmp/cqm-config.toml
nix run .#codex-quota-monitor -- doctor --json --management-base-url http://127.0.0.1:9 --gateway-health-url http://127.0.0.1:9/healthz --state-db off >/tmp/cqm-doctor.json || test "$?" -eq 1
printf '{"access_token":"secret","account_id":"acct-a"}\n' >/tmp/cqm-secret.json
nix run .#codex-quota-monitor -- redact /tmp/cqm-secret.json --secret secret >/tmp/cqm-redacted.json
! grep -q secret /tmp/cqm-redacted.json
nix run .#codex-quota-benchmark -- --help

上面故意指向不可达 CPA 的 doctor 应该输出带明确 fail 项的 JSON，而不是 traceback。

如果本地有 Docker，再运行：

docker build -t codex-quota-monitor:release-check .
docker run --rm codex-quota-monitor:release-check --help
./scripts/ci/smoke-docker-image.sh codex-quota-monitor:release-check cqm-release-check

如果本地没有 Docker，把 GitHub Actions 里的 Docker job 作为阻塞性的 image validation gate。

打 Tag 和发布

只有在明确批准后，才创建 annotated tag 并推送：

git tag -a v0.2.0 -m "codex-quota-monitor v0.2.0"
git push origin v0.2.0

推送 tag 会触发 .github/workflows/release.yml，它应该：

• build 并 smoke-test Python wheel 和 sdist；
• 把 distributions 附到 GitHub Release；
• 只有 PYPI_PUBLISH_ENABLED=true 时才通过 trusted publishing 发布到 PyPI；
• 发布 GHCR images，tag 为 0.2.0 和 0.2；
• 给 GHCR image 附 SBOM 和 provenance attestations；
• 用 keyless cosign 签名已推送的 GHCR image digest。

发布后检查

• GitHub Release 存在 v0.2.0，并包含构建出的 distributions。
• 如果 PYPI_PUBLISH_ENABLED=true，PyPI 暴露 codex-quota-monitor==0.2.0。
• 如果已发布 PyPI，uv tool install codex-quota-monitor==0.2.0 后可以运行 codex-quota-monitor --help、codex-quota-monitor --version、 codex-quota-monitor init --mode user、codex-quota-monitor print-config 和 codex-quota-benchmark --help。
• 如果已发布 PyPI，pipx install codex-quota-monitor==0.2.0 作为兼容路径也可用。
• GHCR 暴露 ghcr.io/xsyxnx/codex-quota-monitor:0.2.0 和 :0.2。

• GHCR 暴露 SBOM/provenance attestations，并且下面的 keyless 验证能通过：

  cosign verify \
    --certificate-oidc-issuer https://token.actions.githubusercontent.com \
    --certificate-identity-regexp 'https://github.com/xsyxnx/codex-quota-monitor/.github/workflows/release.yml@refs/tags/v.*' \
    ghcr.io/xsyxnx/codex-quota-monitor@<digest>
  

• nix run github:xsyxnx/codex-quota-monitor/v0.2.0#codex-quota-monitor -- --help 可用。

• Website 上 quick start、install、troubleshooting、upgrade、agent discovery、use cases 和这份 checklist 的链接都返回 200：

  for path in /quick-start.html /install.html /troubleshooting.html /upgrade.html \
    /agent-discovery.html /use-cases.html /release-checklist.html \
    /forum-post-v0.2.0.html /forum-post-v0.2.0.zh-CN.html; do
    curl -fsSIL "https://xsyxnx.github.io/codex-quota-monitor${path}" >/dev/null
  done
  

• release source tree 里包含 rootless user service、config file 和 reverse-proxy 示例。
• 论坛发帖草稿只指向已发布 artifacts 和当前支持联系方式。

停止条件

• package、Nix、changelog 或 docs 里的版本元数据不一致。
• 本地 tests 或 Nix package/app smoke tests 失败。
• 目标 tag 或 GHCR version 已存在。
• 这次预期发布 PyPI，但 PyPI version 已存在或 trusted publishing 没配好。
• GitHub Actions release workflow 在所有 artifacts 发布完成前失败。
• PyPI 或 GHCR 只发布成功一部分，导致可见安装文档指向缺失 artifacts。
• GHCR image signing、SBOM 或 provenance 生成失败。