企业官网建设流程全解析

Open MCT 版本管理指南：语义化版本、版本发布流程与构建期版本注入实践

【免费下载链接】openmctA web based mission control framework.项目地址: https://gitcode.com/GitHub_Trending/ope/openmct

Open MCT 是一个基于 Web 的任务控制（mission control）框架，其版本号承载着发布节奏、API 兼容性承诺与插件生态兼容三重职责。本文基于仓库内 版本指南（docs/src/process/version.md）撰写，系统讲解 Open MCT 的版本语义、版本递增规则、完整的发布操作流程，并结合 构建配置 与 入口实现 说明版本信息是如何写入应用界面、服务测试人员与插件开发者的。读完本文，你将掌握 Open MCT 版本号从"递增决策"到"打标签、发 npm 包、恢复 -next 快照状态"的完整闭环，也能将同一套流程迁移到依赖 Open MCT 的同团队衍生项目上。

版本指南在开发流程中的定位

Open MCT 的开发遵循"冲刺（sprint）+ 发布（release）"的迭代节奏，详见 开发周期：

• 冲刺（Sprint）：每三周一个冲刺，代表一组可完成并通过测试的改进，冲刺结束时软件处于"半稳定"状态；
• 发布（Release）：每四个冲刺进行一次发布，发布版本经过完整的验收测试，属于稳定版本。

版本指南 与 开发周期、测试计划 共同构成 开发流程 的三份核心文档。版本号递增就发生在 开发周期 中描述的"Ship"（发布）这一过程点——只有通过了发布/冲刺测试的代码快照才会被打标签、被部署。

版本信息的受众

版本指南将消费版本号的人群划分为四类，理解他们各自的需求，才能明白为什么 Open MCT 要同时暴露"版本号 + 修订标识 + 品牌名"三份信息：

版本的三重呈现方式

版本指南要求软件版本在应用界面中以三种方式呈现，AboutDialog.vue 的"Version Information"区域正是这一要求的落地实现：

• 版本号（Version number）：语义化版本号，既唯一标识某个发布，也告知插件开发者与历史版本的兼容性；
• 修订标识（Revision identifier）：使用 git 时的 commit hash，通过唯一标识客户端软件快照，服务内部开发者与测试人员定位问题；
• 品牌名（Branding）：标识当前使用的是哪个变体（部署到具体任务或中心时，Open MCT 通常会被重新品牌化）。

在 AboutDialog.vue 中，这些信息被渲染为：

<ul id="versionInformation" class="t-info l-info s-info"> <li aria-label="Version Number">Version: {{ buildInfo.version || 'Unknown' }}</li> <li aria-label="Build Date">Build Date: {{ buildInfo.buildDate || 'Unknown' }}</li> <li aria-label="Revision">Revision: {{ buildInfo.revision || 'Unknown' }}</li> <li aria-label="Branch">Branch: {{ buildInfo.branch || 'Unknown' }}</li> </ul>

这些buildInfo数据来源于 MCT.js 中构造器对this.buildInfo的初始化：

this.buildInfo = { version: __OPENMCT_VERSION__, buildDate: __OPENMCT_BUILD_DATE__, revision: __OPENMCT_REVISION__, branch: __OPENMCT_BUILD_BRANCH__ };

四个字段（version、buildDate、revision、branch）与 About 对话框中的四行展示一一对应。其中revision（commit hash）与branch（git 分支）直接呼应版本指南中"修订标识"与"开发流（dev vs prod）关联"的诉求。

构建期版本注入的底层原理

__OPENMCT_VERSION__、__OPENMCT_REVISION__等并非运行时变量，而是由 webpack 的DefinePlugin在构建期注入的编译常量。webpack.common.mjs 是它们的定义来源：

new webpack.DefinePlugin({ __OPENMCT_VERSION__: `'${version}'`, __OPENMCT_BUILD_DATE__: `'${new Date()}'`, __OPENMCT_REVISION__: `'${gitRevision}'`, __OPENMCT_BUILD_BRANCH__: `'${gitBranch}'`, __VUE_OPTIONS_API__: true, __VUE_PROD_DEVTOOLS__: false, ... })

其中：

• version在构建脚本启动时从根目录 package.json 读取（JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url)))），当前仓库快照的版本为4.2.0-next，正是"开发期带-next后缀"的典型形态；
• gitRevision与gitBranch通过git rev-parse HEAD与git rev-parse --abbrev-ref HEAD实时获取（见 webpack.common.mjs），因此每次构建产出的revision都能精确对应一个源码快照——这正好实现版本指南中"用 commit hash 唯一标识客户端软件快照"的目标。

这一机制意味着：版本号变更只需修改package.json，无需改动任何业务代码，重新构建即可把新版本注入到界面的 About 对话框中。

语义化版本规范

Open MCT 的版本号遵循 Semantic Versioning 2.0.0（语义化版本 2.0.0）。核心规则如下：

• 版本以major.minor.patch三段式表达；
• 破坏性变更（Breaking changes）：递增major（主版本号）；
• 向后兼容的新功能（Backwards-compatible changes）：递增minor（次版本号）；
• 中性变更（如缺陷修复）：递增patch（修订号）；
• 预发布版本：以连字符分隔的后缀标识，可能不稳定，或不能完全满足兼容性要求。

Open MCT 项目特有版本标准

在语义化版本的基础上，版本指南补充了三条项目级约定：

1. 开发期使用-next后缀

开发过程中，版本号需附加-next后缀，前缀数字应反映下一个预期发布的版本号。例如当前仓库 package.json 中的4.2.0-next，表示下一个稳定版本预期为4.2.0，当前正处于其开发阶段。

2. 1.0.0 之前的递增节奏

在发布 1.0.0 之前：

• minor按"每次发布"递增；
• patch按"每个冲刺"递增。

3. 1.0.0 之后的递增节奏

从 1.0.0 开始，每个完成的冲刺都要更新版本号。具体版本号依据与上一个已发布版本的对比来确定，根据该发布期间变更的性质决定递增 major、minor 还是 patch。指南建议在变更引入时就逐步递增这些数字，这样在发布结束时，只需移除后缀即可得到最终版本号，避免临发布前集中决策带来的风险。

4. 发布前三个冲刺的稳定性后缀

一个发布周期的前三个冲刺可能不稳定，此时仍需生成唯一的版本标识，但应附带后缀以表明该版本不一定具备生产就绪性。推荐后缀如下：

外部 API 的界定范围

版本指南特别澄清："外部 API"指暴露给、文档化给并被插件开发者使用的 API。仅影响 Open MCT 内部使用（或未对外文档化）的接口变更，只需递增patch版本号即可。这一界定决定了 major/minor 递增的触发条件，是插件生态下语义化版本能否"如实地"传达兼容性信息的关键。

版本递增与发布操作流程

冲刺结束时，项目经理（project manager）应按下述流程更新（或委托他人更新）Open MCT 版本号。该角色在 开发周期 中有明确定义；若无专职项目经理，可在团队内按冲刺轮换。

第 1 步：更新 package.json 中的版本号

1. 检出上一个已成功通过测试的冲刺所创建的分支；
2. 移除 package.json 中版本的-next后缀；
3. 校验得到的版本号相对于上一个稳定版本满足语义化版本要求，必要时递增版本号；
4. 若该版本被认为不稳定（比如处于一个发布周期的前三个冲刺），按上文 版本递增规则 附加新后缀（-alpha/-beta/-rc）。

第 2 步：给发布打标签（Tag）

1. 在上一分支上提交 package.json 的变更，提交信息应引用被关闭的冲刺，最好通过 URL 引用 GitHub 上关联的 Milestone；
2. 验证构建仍能完成、应用通过冒烟测试，且与已测试版本的差异仅限于上述版本号变更；
3. 推送新分支；
4. 用版本号给该提交打标签，前缀字母v，例如git tag v0.9.3-alpha；
5. 推送标签到 GitHub，例如git push origin v0.9.3-alpha。

第 3 步：上传发布归档（Release Archive）

1. 使用 GitHub release 界面起草新发布；
2. 选择上一步创建并推送的现有标签，将标签名同时作为发布名称，参考现有发布格式（如Open MCT v0.9.3-alpha）；
3. 视情况将发布标记为pre-release（例如版本号带不稳定后缀时，或版本号低于 1.0.0 时）；
4. 撰写发布说明（Release Notes），简述破坏性变更、增强与缺陷修复及其解决方案；
5. 发布该版本。

第 4 步：发布到 npm

1. 登录 npm；
2. 检出上一步创建的标签；
3. 在 package.json 中将包改为公开（private: false）。注意当前仓库的根 package.json 并未显式声明private字段，且配置了"workspaces": ["e2e"]，发布前需要确认包的公开访问属性；
4. 发布前可用npm publish --dry-run试跑测试包内容；
5. 将包发布到 npmjs registry，例如npm publish --access public。注意：若为预发布版本，需给 npm publish 加上--tag unstable标志；
6. 确认包已成功发布（例如在 npmjs 上查看openmct包）。

第 5 步：在 package.json 中恢复快照状态（Snapshot Status）

发布完成并非流程终点，还需要让主干分支回到"开发中"状态：

1. 基于master分支创建新分支；
2. 移除版本号上的后缀；若无后缀则递增 patch 版本；
3. 追加-next后缀（例如4.2.0→4.2.0-next）；
4. 在master分支上提交 package.json 的变更，提交信息应引用被开启的冲刺，最好通过 URL 引用 GitHub 上关联的 Milestone；
5. 验证构建仍能完成、应用通过冒烟测试；
6. 创建 PR 合并回master分支。

这一"去后缀 → 打标签发布 → 再补-next后缀"的循环，正是当前仓库快照中4.2.0-next这个版本号之所以存在的直接原因，也保证了任何时候master上的版本号都明确表达"当前开发指向的下一个发布版本"。

完整发布流程速查表

依赖项目的协同版本流程

版本指南的最后一部分针对由 Open MCT 团队协同开发、且依赖 Open MCT 的项目：这类项目应遵循与 Open MCT 自身相似的流程，但有两处额外动作：

1. 在移除自身的-next状态时，同时把对 Open MCT 的依赖更新到最新归档版本（即上一步发布的正式版本）；
2. 上述工作完成后，将对 Open MCT 的依赖指回master分支，从而在下一次发布前持续跟随主干开发。

这套协同机制保证了"同团队多项目"之间的版本对齐：子项目发布时依赖的是已发布、可追溯的 Open MCT 版本，而日常开发中又不会因依赖锁死而阻塞跟进 Open MCT 的最新变更。

在仓库中验证版本信息

读者可以在当前仓库中直接验证本文描述的机制：

• 查看 package.json 的name（openmct）与version（4.2.0-next）字段，确认开发快照形态；
• 阅读 webpack.common.mjs 中版本、构建日期、git 修订与分支的注入逻辑，理解"改package.json即改界面版本号"；
• 对比 MCT.js 的buildInfo初始化与 AboutDialog.vue 的渲染，确认"版本号 + 修订标识 + 品牌"三重呈现的实际落点；
• 若需执行构建以观察注入效果，可运行npm run build:dev（开发构建）或npm run build:prod（生产构建），构建产物dist/openmct.js中的__OPENMCT_VERSION__等常量会被替换为当前 package.json 中的真实值（Node 版本要求见 package.json 的engines.node >=24.14.1）。

小结

Open MCT 的版本管理是一套把"语义化版本 + 开发节奏 + 发布操作 + 构建注入"串联起来的完整流程：major/minor/patch的递增决策由 开发周期 的冲刺节奏驱动，-next、-alpha、-beta、-rc后缀在界面与 npm 包中同时标识稳定性，v前缀的 git 标签与 GitHub Release 承载可追溯的发布历史，而 webpack.common.mjs 的DefinePlugin把 package.json 中的版本号连同 commit hash、分支与构建日期一起注入 AboutDialog.vue 的界面展示。对插件开发者而言，理解"外部 API"的界定即可快速判断某个变更是否需要关注 major 递增；对同团队依赖项目，则可直接复用这套流程并同步维护对 Open MCT 的依赖指向。

【免费下载链接】openmctA web based mission control framework.项目地址: https://gitcode.com/GitHub_Trending/ope/openmct