Mackup 版本发布全流程指南:从 Changelog 更新到 PyPI 发布
Mackup 版本发布全流程指南:从 Changelog 更新到 PyPI 发布
Mackup(一个用于备份并同步应用配置文件的跨平台工具)的维护者通过 doc/release.md 定义了一套精简、可重复的发布流程:先整理变更日志与版本号,再提交并打 tag,最后借助 Poetry 完成构建与发布。本篇指南以该文档为骨架,结合仓库中的 Makefile、mackup/constants.py、pyproject.toml 与 mackup/main.py 源码,逐步拆解每一次正式发布背后的操作细节与底层原理。读完本文,你将掌握 Mackup 从开发收尾、版本号同步、Git 提交打签,到通过 make release 发布到 PyPI 的完整实操流程,并能在自己的发布中规避版本不一致、漏推 tag 等常见问题。
发布前的准备:确保本地开发环境可用
正式的版本发布不是从打 tag 开始的,而是从"代码已经就绪、测试通过"开始的。doc/develop.md 给出了标准的本地开发环境搭建方式:
# 安装 pipx,以便隔离运行 Python 包
brew install pipx
# 安装依赖管理与打包工具 Poetry
pipx install poetry
# 进入仓库后安装包含 dev 依赖的环境
cd .../mackup
poetry install --with dev
# 验证本地修改对命令行工具的影响
poetry run mackup --version
Mackup 的 --version 输出并非硬编码在入口处,而是由 mackup/main.py 中的 docopt 参数解析动态拼接的:
args = docopt(__doc__, version="Mackup {}".format(VERSION))
也就是说,poetry run mackup --version 打印出的版本号直接来自 mackup/constants.py 中的 VERSION 常量。这意味着发布前可以先本地运行该命令,确认版本号与期望值一致;同时,仓库 Makefile 中的 test 目标(poetry install --with dev + poetry run pytest)与 ruff 目标(ruff check .)也可用于发布前做最后的回归检查,确保要发布的代码是干净的。
版本号的三处同步:发布的核心步骤
Mackup 的版本号不是单一来源,而是分散在多处,发布时必须逐一同步,否则会出现"命令行显示 0.8.41、但包元数据仍是 0.8.40"这类不一致问题。以当前仓库为例,版本为 0.8.40,需要同步的位置包括:
| 位置 | 文件 | 当前内容 | 作用 |
|---|---|---|---|
| 变更日志版本区 | CHANGELOG.md | ## Mackup 0.8.40 |
对外展示的变更记录 |
| 版本常量 | mackup/constants.py | VERSION = "0.8.40" |
驱动 mackup --version 输出 |
| Poetry 元数据 | pyproject.toml | version = "0.8.40" |
决定 PyPI 包版本号 |
1. 把 WIP 变更整理进新的 Changelog 版本区
CHANGELOG.md 顶部长期保留着一个 ## WIP 区块,用于累积未发布的功能与修复(例如当前 WIP 中就有 DBeaver、rtx、Alacritty TOML 配置、Ghostty 等一批新增支持)。发布第一步,就是把这个 WIP 区块整体改名成新的版本标题(如 ## Mackup 0.8.41),并在此基础上重新开一个空的 ## WIP 区块给下一轮开发使用。从 CHANGELOG 的历史条目可以看到,每条记录都遵循"- 动作 + 对象(via @贡献者)"的格式,发布时保持这种统一格式,既便于读者快速浏览,也便于后续检索。
2~3. 同步版本号:constants.py 与 pyproject.toml
- 递增 mackup/constants.py 中的
VERSION常量。该常量除了被 mackup/main.py 导入用于--version输出外,也被错误提示信息(如找不到存储引擎时的ERROR_UNABLE_TO_FIND_STORAGE)引用,是运行时版本信息的唯一事实来源。 - 递增 pyproject.toml 中的
version字段。Poetry 在构建 wheel/sdist 时以该字段为准,它决定了上传到 PyPI 后的包版本;若与constants.py不一致,用户安装到的版本号与mackup --version显示号就会互相矛盾。
此外,pyproject.toml 中还通过 [tool.poetry.scripts] 声明了 mackup = "mackup.main:main" 这个 console script 入口,这也印证了"发布出去的包最终会以 mackup 命令形态安装到用户环境",版本号正确性直接影响用户端体验。
官方发布流程:八步走
doc/release.md 给出的发布流程完整如下,每一步都不可省略:
- 将 WIP 变更归档到新版本下:在 CHANGELOG.md 中,把
## WIP区块重命名为新的版本号标题,并保留/新建空的 WIP 区块。 - 递增 mackup/constants.py 中的版本号:
VERSION = "X.Y.Z"。 - 递增 pyproject.toml 中的版本号:
version = "X.Y.Z",与上一步保持一致。 - 提交 Git:执行
git commit,提交信息固定为Mackup X.Y.Z(如Mackup 0.8.41),使提交信息与版本号一一对应,方便日后按提交检索每个版本。 - 打 Git 标签:执行
git tag <version>,标签名直接使用版本号(如git tag 0.8.41)。标签与发布版本一一对应,是后续追溯源码状态的关键锚点。 - 推送代码:执行
git push,将提交推到远端仓库。 - 推送标签:执行
git push --tags,这一步经常被遗漏——只推送提交而不推送标签,会导致远端缺少发布标记,后续基于 tag 的检出或归档都会失效。 - 触发发布:执行
make release,由 Makefile 完成清理、构建与上传。
这 8 步的先后顺序是有讲究的:先改文档与版本号(1~3),让"变更记录—运行时版本—包元数据"三者保持一致;再提交打签(4~5),确保 tag 指向的提交里已经包含了正确的版本号;最后推送(6~7)与构建发布(8),保证 PyPI 上发布的产物与 Git 历史严格对应。
make release 底层原理:Poetry 构建与发布
发布流程的最后一步 make release 由 Makefile 定义,其实现非常精简:
release: clean
poetry build
poetry publish
clean:执行rm -rf mackup/__pycache__、rm -rf tests/__pycache__和rm -rf dist/,先清除本地字节码缓存与上一次构建产物,避免旧文件污染新构建。poetry build:基于 pyproject.toml 中的[build-system](poetry-core)与[tool.poetry]元数据,生成 sdist 与 wheel 两类分发产物。poetry publish:将构建产物上传到 PyPI。此步骤需要本机已配置好 PyPI 凭据(如poetry config http-basic.pypi或环境变量),若未配置会在此步失败。
值得注意的是,Makefile 中 release 以 clean 为前置依赖,这与发布流程第 1 步"先整理 CHANGELOG"的节奏形成闭环:整个发布过程同时涵盖了"人要做的事"(改文档、改版本、提交打签)与"机器要做的事"(清理、构建、上传)。
发布后的验证与常见问题
发布完成后,建议做如下验证:
- 通过
git log --oneline确认Mackup X.Y.Z提交存在,通过git tag确认新标签已列出,且git ls-remote --tags能查到远端标签(验证第 7 步是否真正生效)。 - 在干净环境安装刚发布的版本,例如
pip install mackup==X.Y.Z后运行mackup --version,确认与constants.py中的VERSION一致。 - 回到开发分支确认新的
## WIP区块已经就位,后续贡献可以继续累积。
实践中常见的问题与对策:
- 版本号未同步:只改了
pyproject.toml忘了改constants.py(或反之),表现为"安装的包版本与--version输出不一致"。发布前务必用poetry run mackup --version做一次核对。 - 忘记
git push --tags:提交推送成功但标签没推,远端无法通过 tag 定位该版本源码。建议发布清单中把第 6、7 步拆开执行并逐一确认。 - PyPI 凭据缺失:
make release在poetry publish阶段失败。应提前配置 Poetry 的 PyPI 认证信息再执行发布。 - tag 与版本号不匹配:tag 名应严格等于版本号(如
0.8.41),不要加v前缀或自定义名称,以免与Mackup X.Y.Z的提交信息和 Changelog 标题产生歧义。
对于希望参与 Mackup 的开发者,doc/develop.md 中 poetry install --with dev、poetry run mackup --version、make test 的组合即可完成绝大多数本地验证;而真正面向用户的正式版本,则由本文所述的 8 步流程 + make release 这条流水线最终交付。