Sigil 版本发布检查清单全解析：从版本号到 Release 发布的完整流程

• 桌面应用
• 文档

导读

本文基于 Sigil（多平台 EPUB 电子书编辑器）仓库中的 docs/ReleaseChecklist.md 发布检查清单，逐条讲解从构建验证、版本号升级、源码包生成、多平台打包签名，到 SHA256 校验、GitHub Release 发布与多渠道公告的完整发布流程。读完本文，你将掌握 Sigil 官方维护团队的一次标准发版所涉及的每一个可执行步骤、底层版本号机制（CMakeLists.txt、version.xml 与 ChangeLog.txt 的联动关系），以及 CI 工作流（.github/workflows/create_tag.yml）中对打标签与发布环节的自动化实现。

发布清单概览：为什么需要逐项核对

ReleaseChecklist.md开篇即声明：

All items on this list must be completed for a successful release.

（清单中的所有条目都必须完成，才能实现一次成功的发布。）

这意味着 Sigil 的发布不是一次性git push那么简单，而是一条串行且相互依赖的流水线：版本号散落在多个文件中、源码包由 Git 归档生成、各平台二进制包需要分别构建与签名、校验和文件需要手工修正、公告需要同步到多个渠道。任何一个环节遗漏，都可能导致用户拿到错误版本、校验失败或公告缺失。下文按清单顺序逐条展开，并结合仓库源码说明"为什么这样做"。

前置检查：构建可用性与发布材料准备

1. 确保 Sigil 构建并运行（Ensure Sigil builds and runs）

发布的首要前提是 master 分支处于可构建、可运行的绿色状态。仓库通过 GitHub Actions 提供多平台持续构建验证，例如：

• .github/workflows/mac-build.yml
• .github/workflows/win-build.yml
• .github/workflows/build_appimage.yml

这些工作流均以BUILD_TYPE: Release（如 .github/workflows/win-build.yml 第 34 行所示）执行 CMake 构建，覆盖 macOS、Windows 与 Linux（AppImage）三种目标。发布前应确认这些 CI 结果全部通过，并在本地对将要发布的目标平台做一次实机冒烟测试。

2. 编写发布公告（Write release announcement）

发布公告是后续所有公告动作（博客、MobileRead、GitHub Release 正文）的底稿，建议在发布流程早期就起草完成。仓库中有一个用于 CI 自动生成博客发布帖的辅助脚本 .github/workflows/make_post.py，其工作方式是从 GitHub Release 事件负载中读取发布信息（见第 46-80 行的release事件解析逻辑），因此公告正文应当与最终 Release 的name与body保持一致。

3. 更新翻译（Update translations）

Sigil 的界面翻译文件存放在 src/Resource_Files/ts 目录（当前包含 22 个.ts翻译文件），由 Qt Linguist 工具链维护。发版前需要从翻译平台拉取最新的.ts翻译、确保无未提交的翻译更新，并确认新版本中新增的用户可见字符串都已进入翻译流程。仓库维护文档 docs/Translating.md 描述了完整的翻译协作流程。

4. 确保所有构建平台使用最新版 Qt（Ensure Qt is at the latest version）

清单要求：所有将要为其构建软件包的 OS 上，Qt 必须是最新版本。这一点在 CMake 配置中有直接体现：

• 顶层 CMakeLists.txt 第 21-23 行通过QTVER变量控制 Windows 构建下载的 Qt 版本，默认6.8.2，注释明确说明"Used to keep downloaded Qt and PySide6 versions in sync"（用于保持下载的 Qt 与 PySide6 版本同步）；
• 第 33-35 行通过DOWNLOAD_QT开关（默认 0）决定是否下载使用自定义构建的 Qt；
• macOS 与 Windows 的 CI 工作流也各自固定了 Qt 版本，如 .github/workflows/win-build.yml 第 35 行的DOWNLOADQT变量。

此外，仓库 docs/Qt_Patches 目录收录了针对特定 Qt 版本的补丁（如qt672_fix_h6_insertParagraph.patch、qt682_post_install_macos_ignore_bad_cups_cmake_find_failure.patch等），说明官方对 Qt 版本差异有细致的跟踪。发布前需要确认这些补丁与新版 Qt 的兼容性。

版本号三件套：CMakeLists.txt、version.xml 与 ChangeLog.txt

5. 在 CMakeLists.txt 中提升版本号（Bump version in CMakeLists.txt）

Sigil 的构建版本号定义在顶层 CMakeLists.txt 第 60-63 行：

set( SIGIL_MAJOR_VERSION 2 ) set( SIGIL_MINOR_VERSION 8 ) set( SIGIL_REVISION_VERSION 5 ) set( SIGIL_FULL_VERSION ${SIGIL_MAJOR_VERSION}.${SIGIL_MINOR_VERSION}.${SIGIL_REVISION_VERSION} )

SIGIL_FULL_VERSION是一个派生变量，会在多个地方被消费，这是"版本号分散、必须逐一更新"的根本原因。通过仓库检索可以发现它至少被用于：

• installer/Sigil.iss（Inno Setup 安装器脚本）第 9-11 行的AppVerName、AppVersion、VersionInfoVersion，以及第 34 行的安装包输出文件名Sigil-${SIGIL_FULL_VERSION}-Windows-...-Setup；
• src/qt6sigil.cmake 第 89-90 行：将SIGIL_FULL_VERSION以编译宏注入About.cpp与Utility.cpp；
• src/Dialogs/About.cpp 第 33 行：const QString SIGIL_VERSION = QString(SIGIL_FULL_VERSION);，即"关于"对话框显示的版本号；
• src/Misc/Utility.cpp 第 703 行：错误诊断日志中的"Sigil version: " + QString(SIGIL_FULL_VERSION)；
• src/Resource_Files/windows/version.rc.in 第 15、22 行：Windows 资源文件的FileVersion与ProductVersion。

也就是说，提升CMakeLists.txt中的三段版本号后，安装包文件名、About 对话框、日志、Windows 文件属性版本会同时更新。

6. 在 version.xml 中提升版本号（Bump version in version.xml）

根目录的 version.xml 是 Sigil 内置"检查更新"功能的线上数据源，其当前内容为：

<?xml version="1.0" encoding="UTF-8"?> <information> <current-version>2.8.1</current-version> </information>

该文件的消费端是 src/Misc/UpdateChecker.cpp：第 40 行将UPDATE_XML_LOCATION指向 GitHub 上 master 分支的version.xml；第 75-79 行通过内嵌 Python 脚本updatechecker.check_for_updates下载并解析它；第 91 行调用IsOnlineVersionNewer将在线版本与本地SIGIL_VERSION比较，若在线版本更新且用户此前未被告知（第 94 行条件），则弹出提示框引导用户前往下载页（第 96-107 行）。检查频率由第 46 行的SECONDS_BETWEEN_CHECKS = 60 * 60 * 6控制（每 6 小时一次）。

重要提醒：version.xml 由 UpdateChecker 通过raw.githubusercontent.com读取，必须随 release 一起推送到远端 master 分支后，线上检查更新才能生效——这正好呼应清单最后一步"Push git changes"的意义。

7. 在 ChangeLog.txt 中设置发布日期（Set release date in Changelog.txt）

ChangeLog.txt 按版本分组记录变更，当前最新条目为Sigil-2.8.5（第 1 行），下设New Features与Bug Fixes两个小节，并注明贡献者（如(contributed by rinne1998)）。发布时需要在对应版本标题旁补充发布日期，确保用户与打包脚本能对应到时间线。发布公告中引用的变更要点也应与 ChangeLog 保持一致。

提交、打标签与源码包生成

8. 提交版本变更但不推送（Commit version changes but do not push them）

清单明确要求：将上述版本号与 ChangeLog 的改动先commit但不要 push。原因是打标签必须基于包含版本变更的提交，而如果提前 push，中间状态可能被其他人拉取到不完整的版本信息。正确的顺序是：本地提交 → 打标签 → 推送标签与 master。

9. 打版本标签（Tag version）

Sigil 的标签命名遵循语义化版本约定（如2.8.5或v2.8.5，参见 .github/workflows/create_tag.yml 中被注释掉的校验正则^\d+\.\d+\.\d+$）。

仓库提供了自动化打标签的 CI 工作流 .github/workflows/create_tag.yml：通过workflow_dispatch手动触发（第 3-10 行），输入tag_name；第 45 行执行git tag -s <tag_name>（GPG 签名标签，第 31-38 行导入 GPG 私钥并启用git_tag_gpgsign）；第 46 行推送标签；第 52-55 行用git archive生成.tar.gz源码包并做 GPG 分离签名（.sig）；最后第 57-70 行调用ncipollo/release-action创建draft（草稿）Release，将签名文件作为工件上传。这个工作流恰好是清单第 9-14 步在 CI 中的部分自动化体现——草稿 Release 仍需人工补传各平台二进制包。

10. 构建源码包（Build source package）

清单给出的命令：

git archive --prefix Sigil-x.y.z/ -o ../Sigil-x.y.z-Code.zip HEAD

git archive基于当前HEAD（即包含版本变更的提交）导出干净的源码快照，--prefix Sigil-x.y.z/将源码统一放入带版本号的前缀目录，解压后即为Sigil-x.y.z/目录，-o指定输出文件名为Sigil-x.y.z-Code.zip。这与 create_tag.yml 第 52 行的用法一致（那里以.tar.gz形式归档并做 GPG 签名），是源码分发的唯一权威来源——它保证发布包与仓库内被签名的提交完全一致。

多平台打包、签名与校验和

11. 构建软件包（Build packages）

清单要求为OS X与Windows分别构建安装包：

• Windows：由 installer/Sigil.iss（Inno Setup 脚本）驱动打包，产物文件名形如Sigil-2.8.5-Windows-x64-Setup.exe（第 34 行OutputBaseFilename模板）。CI 工作流 .github/workflows/win-build.yml 会先以-DCMAKE_BUILD_TYPE=Release完成构建。另外仓库还维护了 winget 发布流：ci_scripts/winget 目录下的清单文件（Sigil-Ebook.Sigil.yaml、Sigil-Ebook.Sigil.installer.yaml、Sigil-Ebook.Sigil.locale.en-US.yaml）与 .github/workflows/winget.yml（手动触发，通过build.ps1 -Version生成清单并提交 PR），供发布后推送 WinGet 渠道使用。
• macOS：构建细节见 docs/Building_Sigil_On_MacOSX_With_Qt6.txt 与 docs/Building_A_Relocatable_Python_3.14_Framework_on_MacOSX.txt，CI 工作流 .github/workflows/mac-build.yml（Intel）与 .github/workflows/mac_arm64-build.yml（Apple Silicon）分别产出两种架构的软件包。

12. 签名软件包（Sign packages）

清单明确标注OS X 包需要签名。macOS 的签名（Developer ID + notarization）是 Gatekeeper 放行的前提，否则用户打开软件包会遭遇"无法验证开发者"警告。此步骤在清单中单独列出、并注明仅针对 OS X，说明 Windows 侧（如可用时）的 Authenticode 签名可按发布策略另行处理。

13. 生成 SHA256 校验文件（Generate Checksums file）

清单给出的命令：

shasum -a 256 * > Sigil-x.y.z-CHECKSUMS.sha256

并特别附注：

Remove the first line which is the checksum for the empty checksum file produced due to the globing.

这是因为通配符*展开时会把当前目录下已有的校验文件本身也纳入计算——此时该文件还是空的，shasum会为"空文件"生成一个无意义的校验和并作为第一行写入，所以生成后必须删除第一行，只保留各软件包与源码包的 SHA256。最终校验文件的内容形如：

SHA256 (Sigil-2.8.5-Code.zip) = <hash> SHA256 (Sigil-2.8.5-Windows-x64-Setup.exe) = <hash> SHA256 (Sigil-2.8.5-Mac-...pkg) = <hash>

校验文件本身也应随 Release 一起分发，供用户在下载后使用shasum -a 256 -c Sigil-x.y.z-CHECKSUMS.sha256验证包完整性。

发布与公告

14. 在 GitHub 创建 Release（Make Release on GitHub）

将以下四类产物全部上传到 Release 页面：

• Code：源码包Sigil-x.y.z-Code.zip（以及 CI 生成的.tar.gz与对应 GPG.sig签名，见 create_tag.yml）
• OS X：macOS 安装包
• Windows：Windows 安装包
• SHA256 sums：上一步生成的Sigil-x.y.z-CHECKSUMS.sha256

CI 工作流会预先创建 draft Release（.github/workflows/create_tag.yml 第 68 行draft: true），发布者只需把草稿状态切换为正式发布即可，name取Sigil-<version>形式（该工作流第 62 行）。

15-16. 发布公告到博客与 MobileRead（Post release announcement）

清单要求在两处同步发布公告：

• Blog(s)：Sigil 官方博客。仓库提供了自动化发布帖生成工作流 .github/workflows/make_blog_post.yml，它只在 GitHub Release 正式发布事件触发后运行（第 4-5 行），从 release 事件中提取版本信息生成博客文章，并以Auto create <TAGNAME> release blog post为提交信息自动提交（第 45 行）。其配套脚本 .github/workflows/make_post.py 负责解析 release 事件负载中的name与body。
• MobileRead：电子书制作社区的公告帖，需要发布者手工发布，内容与博客公告保持一致（变更要点、下载链接与校验信息）。

17. 推送 git 变更（Push git changes）

最后一步才是 push。将包含版本号提升、ChangeLog 日期、发布标签在内的所有本地提交推送到远端 master 分支。这一步完成后：

• 线上version.xml更新，用户内置的 UpdateChecker（src/Misc/UpdateChecker.cpp）开始提示新版本；
• GitHub Release 与各 CI 自动化（博客帖生成、WinGet 发布）以 master 上的标签为锚点完成联动。

至此，一次完整的 Sigil 版本发布流程闭环。

附录：发布流程速查表

结语

ReleaseChecklist.md虽然篇幅精简，却浓缩了 Sigil 发版的全部关键约束：版本号三处联动（CMake、version.xml、ChangeLog）、commit 与 push 分离（保证标签与发布包的可追溯性）、源码包必须来自 git archive（保证源码与提交一致）、SHA256 校验文件首行需剔除（防止通配符自引用污染校验数据），以及push 必须放在最后（version.xml 与 UpdateChecker 的在线联动）。配合仓库中的 CI 工作流，这份清单既适合 Sigil 维护者按步骤执行，也适合想自建发布流水线的开源项目作为范本参考。

• 桌面应用
• 文档