NoneBot 插件发布速记

插件类项目的发布最怕流程散。你知道大概要做什么，但每次都要重新想一遍顺序，最后就容易漏掉检查、漏打 tag，或者把 release commit 和功能 commit 混在一起。

这篇文章把一套够用的发布顺序整理成速记版。

一个最小发布清单

假设当前最新版本是 0.1.6，下一次准备发 0.1.7：

git checkout master
git pull --ff-only

uv lock
pre-commit run --all-files
uvx basedpyright
uv run pytest

git add -A
git commit -m "fix: 描述这次改动"

uv version --bump patch
pre-commit run --all-files
uvx basedpyright
uv run pytest

git add pyproject.toml uv.lock
git commit -m "chore(release): bump version to v0.1.7"

git tag -a v0.1.7 -m "v0.1.7"
git push origin master
git push origin v0.1.7

这组命令的核心思路，是把“功能改动”和“版本发布”拆成两个提交。

为什么要分两次提交

推荐顺序是：

1. 先完成功能修改并提交
2. 再 bump 版本并单独提交

这样做的好处是：

• Git 历史更清楚
• 以后回头看 release 更容易
• 出问题时更容易定位是代码改动还是版本变更

bump 前后都要跑检查

很多人会在改完代码后跑一轮检查，但 bump 版本后就直接发。更稳的做法是 bump 后再跑一轮：

pre-commit run --all-files
uvx basedpyright
uv run pytest

虽然版本变更本身通常不影响逻辑，但这一步能防止你把“未更新锁文件”或“额外格式化变更”一起带进 release。

pre-commit 没装怎么办

如果提交时看到：

`pre-commit` not found. Did you forget to activate your virtualenv?

可以先装工具：

uv tool install pre-commit
pre-commit install

然后确认：

pre-commit --version
pre-commit run --all-files

什么时候用 patch、minor、major

版本提升通常按这三类走：

uv version --bump patch
uv version --bump minor
uv version --bump major

如果你自己还没建立严格的语义版本纪律，至少先把 patch / minor 分清：

• patch：修 bug、小修正
• minor：新增功能，但不破坏现有用法

发布失败时先看哪里

basedpyright 因 warning 失败

如果项目允许 warning 存在但不阻塞发布，可以在配置里显式设置：

[tool.basedpyright]
failOnWarnings = false

release 工作流报 release not found

这通常说明工作流在上传资产前，没有先创建 GitHub Release。常见修法是先执行：

gh release create vX.Y.Z --verify-tag --title vX.Y.Z --generate-notes

再上传构建产物。

一句话总结

NoneBot 插件发布本质上不复杂，复杂的是每次都靠记忆临时拼流程。把顺序固定下来，发布就会从“容易慌的动作”变成“稳定重复的动作”。