Mackup 版本发布全流程指南:从 Changelog 更新到 PyPI 发布

原创2026-09-21 20:22:191,725 阅读
文章标签:开发工具CLI配置管理

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 给出的发布流程完整如下,每一步都不可省略:

  1. 将 WIP 变更归档到新版本下:在 CHANGELOG.md 中,把 ## WIP 区块重命名为新的版本号标题,并保留/新建空的 WIP 区块。
  2. 递增 mackup/constants.py 中的版本号:VERSION = "X.Y.Z"。
  3. 递增 pyproject.toml 中的版本号:version = "X.Y.Z",与上一步保持一致。
  4. 提交 Git:执行 git commit,提交信息固定为 Mackup X.Y.Z(如 Mackup 0.8.41),使提交信息与版本号一一对应,方便日后按提交检索每个版本。
  5. 打 Git 标签:执行 git tag <version>,标签名直接使用版本号(如 git tag 0.8.41)。标签与发布版本一一对应,是后续追溯源码状态的关键锚点。
  6. 推送代码:执行 git push,将提交推到远端仓库。
  7. 推送标签:执行 git push --tags,这一步经常被遗漏——只推送提交而不推送标签,会导致远端缺少发布标记,后续基于 tag 的检出或归档都会失效。
  8. 触发发布:执行 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 这条流水线最终交付。

登录后查看全文
mackup