外观
Git Tag 规范文档
1. 目的
规范 UmiUDI 项目的 Git Tag 命名及备注(Remark)格式,确保发布历史清晰、可追溯,并能够配合 GitHub Actions 自动生成高质量的发布说明。
2. Tag 命名规则
Tag 名称应严格遵循以下语义化格式: vMajor.Minor.Patch.Build
- 命名示例:
v1.0.0.15 - 版本说明:
Major: 主版本号(重大架构调整)。Minor: 次版本号(新功能发布)。Patch: 修订号(Bug 修复、微调)。Build: 构建流水号(频繁发布或修订版)。
- 注意:Git Tag 版本号主要用于 Git 仓库的节点标识,可以根据发布频率递增,不必与软件内部二进制版本号(
AssemblyInfo.cs)强制保持完全同步。
3. Release 标题规范
GitHub Release 的标题应由脚本自动提取 Tag 备注的第一行。为了区分更新性质,标题必须包含 更新类别 前缀。
3.1 标题格式
[更新类别]: v[软件版本号] - [核心摘要]
3.2 更新类别(Type)定义
功能:新增功能、业务逻辑实现。
修复:Bug 修复、逻辑缺陷校正。
优化:性能改进、代码重构、UI/UX 调整。
文档:规范文档、README、注释等非代码变动。
部署:CI/CD 脚本(release.yml)、打包配置、环境设置。
发布:正式版本的全量打包发布。
示例:
修复: v1.0.0.12 - 修正 UDI 审计日志动作标签错误示例:
文档: v1.0.0.16 - 发布 Git Tag 备注规范文档
4. Tag 备注(Remark)规范
创建 Tag 时必须使用附注标签(Annotated Tag),禁止使用轻量标签。备注内容必须为 中文。
3.1 备注指令示例
bash
git tag -a v1.0.0.15 -m "备注内容"4.2 备注内容结构
备注内容应包含以下三个部分:
- 标题行:
[更新类别]: v[软件版本号] - [核心摘要](此行将自动成为 Release 标题) - 正文行:详细的变更列表(分条罗列)。
- 其他说明:如已知问题或升级提示。
4.3 优秀示例
text
修复: v1.0.0.12 - 修正 UDI 审计日志动作标签错误
1. 修复 UDI 首检和抽检流程中,审计日志动作标签被错误标记为“下推”的问题。
2. 修正后的标签分别为“首检”和“抽检”,提高了审计追溯的准确性。
3. 在 udi_dy_review 表中增加了缺失的 udi_dy_ditype 字段映射。4. 构建架构与约束
- 构建机制升级(Self-Hosted Runner):
- 本项目 CI 流水线现已统一配置为本地自建执行机(
runs-on: [self-hosted, Windows, X64]),执行机路径为D:\actions-runner。 - 0 额度消耗保障:所有 Tag 触发的构建任务均由本地电脑承载,不扣除 GitHub 官方月度 2000 分钟配额,彻底告别额度耗尽与超时卡死风险。
- 本项目 CI 流水线现已统一配置为本地自建执行机(
- 发布规范约束:
- 禁止使用英文备注:所有对外发布的 Tag 说明必须使用规范的中文叙述。
- 禁止空备注:Tag 备注不得为空或仅包含“update”、“fix”等无意义词汇。
- 版本锁定确认:在发布前,必须确认
AssemblyInfo.cs和docs/CHANGELOG.md中的版本号符合本次发布预期。 - 严禁重复打同一 Tag:不得对同一个 Tag 反复删除并强制覆盖推送(
git push --force origin v...),避免引发 CI 连锁排队。 - 适用范围隔离(仅限 PC 端):本规范及自建 Runner 仅适用于 PC 桌面端仓库(
UmiUDI-Enterprise)。移动端(UmiPDA)采用极速本地热更新脚本(publish.bat),严禁往移动端推送 Tag 触发云端 Actions。
5. 标准发布触发流程(SOP)
完成代码功能开发并经本地测试验证后,执行以下 4 步即可触发自动化全流程发布:
- 代码提交:完成业务改动,确保主干代码已提交并推送到
master。 - 创建 Tag:按照本规范在本地创建带规范中文备注的附注 Tag:bash
git tag -a v1.2.1.22 -m "优化: v1.2.1.22 - 修复包装关联抽屉弹窗并优化更新流" - 推送 Tag:bash
git push origin v1.2.1.22 - 自动流水线执行:
- GitHub 自动通知本地
UmiUDI-Runner执行任务; - 本地 Runner 自动完成 .NET 9 编译发布、Inno Setup 打包(生成
UmiUDI-Setup-1.2.1.22.exe安装包); - 自动创建 GitHub Release 页面并将 Tag 备注解析为 Release Body;
- 自动生成 MD5 增量清单并同步推送至 Gitee / GitHub 更新仓库(
UmiUDI-Update)。
- GitHub 自动通知本地
- 终端生效:终端用户无论是新装(下载 Setup.exe)还是存量升级(热更新检测),均可即时获得最新版本。
修订日期:2026-09-04(接入本地 Self-Hosted Runner 自动化流水线)