跳转到内容
Lingchu Bot

发布版本

在 main 上提交发布说明，然后用 bump 输入手动触发 release.yml 即可完成 Lingchu Bot 发布。不再需要推送 releases/<bump> 分支 —— task release:publish BUMP=... 改为运行 gh workflow run release.yml -f bump=...。发布版本完全由工作流用 uv version --bump 从最新 tag 推导；开发者不写版本文件。release.yml 复用 ci-builds.yml::versioned-build 在每日定时任务中使用的同一条 ci:version:bump → ci:version:precheck → ci:version:write-config → ci:version:postcheck 流水线，因此 PEP 440 版本推导只此一份。

bump 输入

Section titled “bump 输入”

bump 输入编码 bump 意图而非字面量版本号。工作流通过 uv version --bump 从最新 git tag 推导版本号：

bump BUMP_LEVEL BUMP_PRERELEASE 推得的版本
major major dev 下一个 major + .dev1
minor minor dev 下一个 minor + .dev1
patch patch dev 下一个 patch + .dev1
stable patch stable 下一个 patch（无 pre-release 段）
alpha patch alpha 下一个 patch + a1
beta patch beta 下一个 patch + b1
rc patch rc 下一个 patch + rc1

字面量版本号从不被接受为输入。工作流的 case 语句会用清晰报错拒绝它们。

本地发布流程

Section titled “本地发布流程”

  1. 切回最新的 main

    Section titled “切回最新的 main”
    Terminal window
    git switch main
    git pull --ff-only

  2. 运行 task release:prepare

    Section titled “运行 task release:prepare”
    Terminal window
    task release:prepare BUMP=stable

    任务会：

    • 校验 BUMP 必须是七个允许值之一。
    • 调用 task ci:version:bump BUMP_LEVEL=patch BUMP_PRERELEASE=stable DRY_RUN=true 预览下一个版本，不修改 pyproject.toml。
    • 若 .github/releases/<computed_version>.md 不存在则脚手架出该文件。

    它作用于当前分支（main）—— 不会写版本文件，也不会创建 releases/<bump> 分支。发布版本完全由工作流用 uv version --bump 从最新 tag 推导。

  3. 编辑发布说明

    Section titled “编辑发布说明”

    打开 release:prepare 输出的 .github/releases/<version>.md，添加 Highlights、破坏性变更与迁移说明。

  4. 更新 changelog 并提交

    Section titled “更新 changelog 并提交”

    在 CHANGELOG.md 增加 ## [<version>] - YYYY-MM-DD 章节并更新底部 compare 链接，然后提交：

    Terminal window
    git add .github/releases/<version>.md CHANGELOG.md
    git commit -m "🔧 chore(release): release <version>"
    git push origin main

  5. 手动触发发布

    Section titled “手动触发发布”
    Terminal window
    task release:publish BUMP=stable

    该命令运行 gh workflow run release.yml -f bump=stable，对已推送的 main commit 派发 release.yml。工作流会推导版本、把版本文件提交回 main，并在同步后的提交上打 tag。

发布工作流做了什么

Section titled “发布工作流做了什么”

release.yml 顺序执行五个 job：

Job 职责
validate 从 bump 派发输入推导 BUMP_LEVEL / BUMP_PRERELEASE；依次执行 ci:version:bump（uv，从最新 tag）→ precheck → write-config → postcheck；定位 .github/releases/<version>.md；把计算出的版本号透出给下游 job。
build 把推导出的版本文件写入工作树、提交并推送到触发分支（main），然后执行 task ci:build；上传 wheel + sdist。
publish-pypi 签发 SLSA Build L3 provenance；通过 Trusted Publishing / OIDC 发布到 PyPI。
publish-image 构建并推送 Docker 镜像到 GHCR；stable bump 同时打 latest 标签（其它仅打 ${version} + ${version%.*}）。
github-release 同步到最新 main 提交（版本同步提交），在该提交上创建 v<version> git tag，并用 .github/releases/<version>.md 内容作为正文创建 GitHub Release。

validate 与 build 调用的是与 versioned-build 在每日定时任务中相同的 ci:version:bump 任务，版本号事实来源只有一份。

故障排查

Section titled “故障排查”
现象 原因 修复
Invalid release branch / input: <name> bump 输入不是七个 bump 名称之一。 改用 major / minor / patch / stable / alpha / beta / rc。
Missing release notes: .github/releases/<version>.md 触发前未提交说明文件。 运行 task release:notes BUMP=<bump> 脚手架，提交并推送后再触发。
Tag v<version> already exists on origin Tag 已被发布；ci:version:tag-only 跳过创建。 确认 tag 与 commit SHA 一致；如需重发，先在 origin 删除 tag 再重跑工作流。
重跑后版本不一致 工作流推导的版本与上次运行不同。 build job 会把 CI 推导的版本文件提交到 main；github-release job 在同步后的提交上打 tag。检查最终 commit 与 tag。