跳转到正文

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 备注内容结构 ​

备注内容应包含以下三个部分:

  1. 标题行:[更新类别]: v[软件版本号] - [核心摘要] (此行将自动成为 Release 标题)
  2. 正文行:详细的变更列表(分条罗列)。
  3. 其他说明:如已知问题或升级提示。

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 分钟配额,彻底告别额度耗尽与超时卡死风险。
  • 发布规范约束:
    • 禁止使用英文备注:所有对外发布的 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 步即可触发自动化全流程发布:

  1. 代码提交:完成业务改动,确保主干代码已提交并推送到 master。
  2. 创建 Tag:按照本规范在本地创建带规范中文备注的附注 Tag:
    bash
    git tag -a v1.2.1.22 -m "优化: v1.2.1.22 - 修复包装关联抽屉弹窗并优化更新流"
  3. 推送 Tag:
    bash
    git push origin v1.2.1.22
  4. 自动流水线执行:
    • 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)。
  5. 终端生效:终端用户无论是新装(下载 Setup.exe)还是存量升级(热更新检测),均可即时获得最新版本。

修订日期:2026-09-04(接入本地 Self-Hosted Runner 自动化流水线)

UmiUDI & Drug 医疗器械与药品唯一标识全生命周期追溯系统