企业官网建设流程全解析

• 无人机
• 智能硬件

导读

本文依据 QGroundControl（QGC）官方开发者文档，系统讲解其开源仓库的版本发布与分支管理策略：从vX.Y.Z语义化版本规范，到Stable_VX.Y稳定分支、master每日构建、Patch 补丁发布，再到创建新 Stable 的完整 Git 标签操作流程。全文结合仓库内 release.yml、release_tag_check.py、Git.cmake 等源码与 CI 配置，说明标签如何驱动版本号生成与发布管道，帮助读者掌握 QGC 乃至同类跨平台项目的可复现发布工程实践。

语义化版本（Semantic Versioning）

QGC 的所有发布版本号遵循语义化版本规范，采用三段式格式vX.Y.Z：

• X：主版本号（Major），代表重大功能变更或破坏性更新；
• Y：次版本号（Minor），代表向后兼容的新功能累积；
• Z：补丁版本号（Patch），代表针对既有版本的缺陷修复。

以v前缀开头，例如v4.2.0。该格式不仅是展示用版本号，还直接参与 CI 的发布判定：仓库中的 release_tag_check.py 用正则^v\d+\.\d+\.\d+$精确匹配发布标签，任何带-rc、-dev后缀或不符合格式的标签都不会触发发布流水线。

Stable 稳定构建

Stable 构建是 QGC 提供的最高质量构建，面向普通用户日常使用，其补丁版本会定期发布以修复重要问题。

分支与标签约定

• Stable 构建从一个独立分支构建，分支命名格式为Stable_VX.Y（注意：分支名不含补丁号，例如Stable_V5.1）；
• 该分支上每发布一个补丁版本，就打一个对应格式vX.Y.Z的 Git 标签，标记该补丁发布对应的源码提交点；
• 一个 Stable 分支可以挂载多个补丁标签（vX.Y.0、vX.Y.1、vX.Y.2……）。

也就是说：分支粒度是"主.次"，标签粒度是"主.次.补丁"，二者一一对应地记录每次对外发布的确切源码状态。

Patch 补丁发布（Patch Releases）

补丁发布包含对 Stable 版本足够重要、必须要求用户更新、且足够安全不至于破坏稳定版本质量的修复。补丁发布只递增补丁版本号 Z。

补丁发布分为两个阶段：

开发阶段：获批的修复直接提交到当前 Stable 分支，在分支上排队积累，直到决定发布下一个补丁版本。与此同时，对 Stable 分支的提交/变更必须同步移植回 master 分支（通过 cherry-pick 或独立 Pull Request），保证两个分支不会分叉失衡。

发布阶段：决定发布补丁版本时，构建发布二进制，并在 Stable 分支上为对应源码打上新的补丁标签（标签号与补丁版本号一致）。

:::info 要点新分支只为主版本/次版本发布而创建，补丁发布不创建新分支。:::

Daily 每日构建

开发阶段

Daily 构建从master分支构建，所有新功能开发都在 master 上进行。master 的状态代表下一个次版本或新主版本（取决于变更规模）。

每日构建不与任何 Git 标签关联——发布的每日构建始终等于仓库当前 HEAD，即"仓库是什么状态，发布就是什么状态"。这意味着：

• 无需维护版本号分支，开发流线性推进；
• 版本号由 CI 在构建时临时派生（见下文"Git 标签驱动的版本号生成"）。

发布阶段（Lockdown 锁定模式）

当决定发布新的主/次版本时，master 会进入初始锁定模式（lockdown）：

1. 此阶段只接受对本次发布重要的修复类 Pull Request；
2. 锁定期间禁止向 master 合入新功能；
3. 当与本次发布相关的修复频率降低到低水平时，从 master 创建新的 Stable 分支——创建完成后 master 即可继续前进，承载"最新最强"的功能；
4. 修复继续在 Stable 分支上进行，直到（理想情况下经过短暂时间后）被认为可以发布；
5. 此时为新 Stable 分支打上新版本标签，完成首个 Stable 发布。

Custom 定制构建

如果开发者基于 QGC 源码构建自己的定制版本，仓库为定制构建的分支策略提供了参考方案，详见 定制构建发布流程。该文档系统介绍了三类定制构建形态：与上游 Stable 同步的 Synchronized Stable、独立于上游发布节奏的 Out-Of-Band Stable，以及基于定制 master 的 Daily 构建，并给出了从首次同步 Stable 起步、后续按需做补丁发布或双轨并行（Out-Of-Band + Daily）的建议路径。

创建新 Stable 的完整操作流程

主版本/次版本发布（Major/Minor Version）

1. 创建 Stable 分支：从 master 创建分支Stable_VX.Y，其中 X 为主版本号、Y 为次版本号。例如发布 Stable 5.1 时创建Stable_V5.1。

2. 在 master 上打每日版本基准标签：在分支点之后的 master 提交上创建带注释的标签（annotated tag），命名为vX.Y.0-dev，其中次版本号比新 Stable大 1。例如创建 Stable 5.1 时，标签应为v5.2.0-dev。git describe会借助该标签派生每日构建的版本号（About 对话框、AndroidversionCode、Deb/RPM 的 release 字段）。-dev后缀使其不会被vX.Y.Z通配规则匹配到，从而不会触发发布构建。示例命令：

   git tag -a v5.2.0-dev -m "QGroundControl v5.2 daily version base"

   关键注意：标签推送会从被标记的那个提交上运行工作流，因此该提交必须已经包含vX.Y.Z发布标签过滤器；绝不要把标签打在更早的、工作流仍会触发v*的旧提交上。

3. 在新 Stable 分支上打发布标签：在新建的 Stable 分支上创建带注释标签vX.Y.0，使用正确的主/次版本号。示例：

   git tag -a v4.2.0 -m "QGroundControl v4.2.0"

   推送该标签到仓库即会启动构建。CI 只在被标记提交可从某个Stable*分支到达时，才把发布标签产物发布到 S3 的latest/目录；在其他任何位置推送vX.Y.Z标签都会被忽略。

4. 验证构建产物：构建完成后，确认各平台产物已正确上传到 S3（路径形如https://qgroundcontrol.s3.us-west-2.amazonaws.com/latest/...），并冒烟验证产物至少能正常启动。

5. 更新版本通知文件：将https://qgroundcontrol.s3.us-west-2.amazonaws.com/latest/QGC.version.txt更新为最新 Stable 版本号。用户下次启动 QGC 时便会收到新 Stable 可用的通知。

6. 等待 CDN 缓存刷新：CloudFront 缓存的下载内容最长需要 24 小时刷新；若需提前生效，必须手动失效缓存。

补丁版本发布（Patch Version）

创建新补丁版本与上述流程相同，区别在于：跳过第 1、2 步（不创建新分支、不打-dev基准标签），并在第 3 步将补丁版本号按需递增。例如从v4.2.0发布补丁时打v4.2.1。

源码级佐证：CI 如何识别发布标签

上述"标签在 Stable 分支上才发布"的规则，在仓库 CI 配置中有完整实现：

• release_tag_check.py：核心判定逻辑。先通过正则^v\d+\.\d+\.\d+$校验标签名称，再执行git branch -r --contains HEAD --list 'origin/Stable*'检查该提交是否被 Stable 分支包含，两者同时满足才输出release_tag=true，否则发出告警并拒绝触发发布。
• _detect-changes.yml：各平台构建工作流（Linux/Windows/macOS/Android/iOS）通过该共享工作流在标签推送时调用上述脚本，采用fail-closed（失败即拒绝）策略——标签判定结果为空即视为不可发布。
• release.yml：发布协调流水线，使用 semantic-release 计算新版本，并经由 release_builds.py 向 Linux、Windows、MacOS、Android、iOS 五个平台工作流分发构建任务，最终汇总产物、生成 SBOM 并上传 GitHub Release。
• aws-upload/action.yml：上传 S3 的步骤中，latest/目录（即公开稳定下载入口）仅当github.ref_type == 'tag'且release_tag_check判定为 true 时才写入，其余构建产物只进入 builds 目录，从机制上杜绝误发布。

源码级佐证：Git 标签如何驱动版本号生成

文档中提到的git describe版本派生机制，在构建系统 cmake/modules/Git.cmake 中有完整实现：

• 通过git describe --always --tags得到完整版本字符串（Git.cmake），例如从v5.2.0-dev基准派生v5.2.0-dev-37-gabc1234这类每日版本串；
• 再通过git describe --always --tags --abbrev=0得到最近的干净版本标签（Git.cmake），并正则解析出主/次/补丁三段（Git.cmake）；
• 距最近标签的提交数-<N>-g<sha>被提取为QGC_APP_VERSION_DEV（Git.cmake），"-dev后缀不进入vX.Y.Z匹配"正是由这一解析逻辑保证的——干净版本标签只取数值前缀，标记类标签（如v5.2.0-dev）只保留在完整版本字符串中；
• 最终版本信息写入 qgc_version.h.in 生成的qgc_version.h，供 About 对话框等界面使用；
• Android 的versionCode/versionName通过 AndroidManifest.xml 中的%%INSERT_VERSION_CODE%%、%%INSERT_VERSION_NAME%%占位符注入，QGC_APP_VERSION_DEV保证每日构建获得唯一递增的版本码；
• 桌面端打包同样消费该信息：Deb 与 RPM 包的 release 字段为${QGC_APP_VERSION_DEV}.g${QGC_GIT_HASH}（见 CreateCPackDeb.cmake 与 CreateCPackRPM.cmake），Arch 包则去掉v前缀使用版本串（CreateArchPackage.cmake）。

小结：一套自洽的发布闭环

QGC 的发布体系可以概括为一条自洽闭环：

1. master承载功能开发，产出每日构建，版本号由vX.Y.0-dev基准标签经git describe实时派生；
2. 发布窗口到来时 master 进入lockdown，随后切出Stable_VX.Y分支并打vX.Y.0标签，触发五平台构建；
3. CI 通过"标签名正则 + Stable 分支可达性"双重校验，确保只有真正的稳定标签能进入 S3latest/公开下载目录；
4. 后续补丁直接在 Stable 分支打vX.Y.Z递增标签，并同步回移植到 master，两个分支始终在语义化版本的坐标系中对齐。

对于基于 QGC 做定制构建的团队，可以在该机制之上叠加 定制构建发布流程 中描述的 Synchronized Stable / Out-Of-Band Stable / Daily 组合策略，实现与上游节奏解耦、又可持续吸收上游修复的发布管理。

• 无人机
• 智能硬件