企业官网建设流程全解析

FreeCAD 如何用 sync_version.py 检查并同步 version.json、pixi.toml 与 Fedora spec 中的版本号？

【免费下载链接】FreeCADOfficial source code of FreeCAD, a free and opensource multiplatform 3D parametric modeler.项目地址: https://gitcode.com/GitHub_Trending/fr/FreeCAD

在 FreeCAD 仓库中，版本号存在多处副本：version.json是版本与项目名的唯一数据源，而 pixi.toml 的[workspace]段和 Fedora 打包文件 package/fedora/freecad.spec 的Name:、Version:字段各自维护一份。手工改version.json后如果漏改了另外两处，CI 的 Lint 工作流就会报版本不同步。仓库为此提供了脚本 src/Tools/sync_version.py，用一条命令即可完成“检查是否一致”和“把两个打包文件更新到与 version.json 一致”两个动作。本文给出该脚本的实际用法、输出判断和 CI 校验方式。

版本数据从哪来：version.json 的字段

脚本只读取仓库根目录的 version.json，其中关键字段及官方注释如下：

{ "name": "FreeCAD", "version_major": 26, "version_minor": 3, "version_patch": 0, "version_suffix": "dev", "build_version": 0 }

各字段含义见文件内的*_note注释：

• version_patch：补丁版本号，例如 0.18.4 发布中的 4；
• version_suffix：开发快照填"dev"，候选发布版填"RC1"等，正式发行版填空字符串；
• build_version：同一版本重新发布时使用（例如使用了更新的 LibPack）。

脚本内部把这份数据转换出多种版本写法（见VersionInfo的属性定义与 src/Tools/tests/test_sync_version.py 中的断言）：

同步时各目标文件使用其中一种：pixi.toml写simple格式，spec 文件的Version:写rpm格式。

检查一致性：--check

官方用法说明写在 src/Tools/sync_version.py 的文件头注释里：

python src/Tools/sync_version.py --check # verify consistency (no changes) python src/Tools/sync_version.py --update # update all files

说明指出脚本设计为在仓库根目录下运行。--check只报告、不修改任何文件：

python src/Tools/sync_version.py --check

脚本按SYNC_TARGETS列表逐个检查两个目标文件，每个文件的输出行为在源码run()中定义：

• OK: <路径>——该文件已与 version.json 一致；
• OUT OF SYNC: <路径>——该文件不一致（check 模式下不写入）；
• SKIP: <路径> (file not found)——文件不存在时跳过，不会中断。

结尾汇总行：全部一致输出All files are in sync.，否则输出Files are out of sync. Run with --update to fix.并以退出码 1 结束；参数不合法（不是--check或--update）时打印用法并以退出码 2 结束。

以仓库当前version.json（26.3.0 + dev）对应的状态为例，一致时的输出类似（文档示例，具体值随版本变化）：

version.json: FreeCAD 26.3.0-dev OK: pixi.toml OK: package/fedora/freecad.spec All files are in sync.

更新不一致的文件：--update

--update会实际改写磁盘上的目标文件（副作用仅限这两个文件中的对应字段，其余内容不动，这一点由测试test_preserves_other_fields和test_update_does_not_modify_synced_files覆盖）：

• pixi.toml：只替换[workspace]段内的version字段，写成simple格式（如"26.3.0"），后缀被丢弃；
• package/fedora/freecad.spec：用正则替换Name:为 version.json 中项目名的小写形式（freecad），Version:写成rpm格式（如26.3.0~dev；version_suffix为空时不带~后缀）。

python src/Tools/sync_version.py --update

运行后对被修改的文件打印UPDATED: <路径>，未变化的仍是OK:，结尾输出All files updated.或All files are in sync.。

一个完整的“升版本”操作路径因此是：修改version.json→ 运行--update重写两个打包文件 → 再运行--check确认全部OK。--update是幂等的，对已一致的文件不会再次改写。

CI 中如何使用这条检查

Lint 工作流 .github/workflows/sub_lint.yml 中包含一个 “Check version sync” 步骤：

- name: Check version sync if: always() run: python3 src/Tools/sync_version.py --check

该步骤与 Lint 中的其它检查一样在 CI 上无条件执行（if: always()）。也就是说，只要提交中的version.json、pixi.toml或 spec 文件三者不一致，--check返回退出码 1，这一步就会失败。本地推送前可以先自行运行一次--check提前发现这类差异。

已知行为与限制

• 同步范围只覆盖SYNC_TARGETS列出的两个文件（pixi.toml、package/fedora/freecad.spec），仓库中其它含版本号的文件不在此脚本职责内；
• 目标文件缺失时打印SKIP并跳过，不会报错，也不会影响退出码判定之外的其它文件；
• 脚本通过自身文件位置推算仓库根目录（Path(__file__)...parent.parent.parent），官方用法仍要求从仓库根目录执行；
• 只有标准库依赖（json、re、sys、dataclasses、pathlib），无额外安装步骤。

如果想在改动脚本本身时确认行为没有回归，可以查看 src/Tools/tests/test_sync_version.py，其中用临时目录构造了 version.json、pixi.toml 与 spec 的最小仓库，覆盖了后缀格式转换、check 检出不同步、update 后 check 转一致、缺失文件跳过等场景。

【免费下载链接】FreeCADOfficial source code of FreeCAD, a free and opensource multiplatform 3D parametric modeler.项目地址: https://gitcode.com/GitHub_Trending/fr/FreeCAD