插件版本号规范化管理规范

1. 总则

1.1 文档目的

为统一基于 NocoBase 框架开发的自定义扩展插件的版本编号规则、版本升级场景、版本适配要求，规范插件迭代、发布、兼容适配流程，解决插件功能迭代、框架版本升级带来的版本混乱、兼容不明确、追溯无依据等问题，保障插件版本可追溯、兼容可管控、迭代可规范，特制定本规范。

1.2 适用范围

本规范适用于所有基于 NocoBase 开源框架二次开发的自定义扩展插件，包含业务功能插件、页面拓展插件、数据处理插件、接口拓展插件、权限定制插件等所有自研插件的版本定义、升级、发布与维护工作。

1.3 核心原则

双版本独立管控：严格区分 NocoBase 框架底层版本、自研插件业务版本，两个版本独立迭代、单独标识，互不混淆。
语义化版本：采用通用语义化版本规则，通过版本号直观区分功能迭代、问题修复、兼容调整。
兼容优先升级：插件与 NocoBase 框架出现不兼容时，必须优先升级插件版本，标注适配框架版本范围。
版本可追溯：每一次版本升级必须对应明确的变更内容，留存版本更新日志。

2. 版本基础定义

2.1 双版本体系说明

NocoBase 自研插件体系包含两套独立版本标识，所有插件必须同时明确标注，缺一不可：

NocoBase 框架版本：指插件开发、运行所依赖的 NocoBase 底层框架官方版本（如 1.20.0、1.21.5），用于定义插件的运行环境兼容范围。
自研插件版本：指我方自主开发扩展插件的业务版本，用于标识插件自身的功能迭代、修复、优化状态，遵循本规范版本升级规则。

2.2 插件版本号格式标准

自研插件统一采用 主版本号.次版本号.修订号 三段式语义化版本格式，格式示例：1.0.0、1.3.2。

主版本号（第一位）：重大版本迭代，代表插件整体架构、核心逻辑、功能体系发生颠覆性变更，不兼容旧版本插件数据或使用方式。
次版本号（第二位）：功能迭代版本，代表新增业务功能、拓展插件能力、优化原有核心功能，向下兼容旧版本。
修订号（第三位）：修复优化版本，代表 Bug 修复、细节优化、性能微调、文案调整，无新增功能，完全向下兼容。

3. 版本升级场景与规则

结合插件开发、框架适配全场景，明确各场景对应的版本升级规则，所有迭代必须严格对应版本号变更。

3.1 修订号升级（PATCH）

适用场景（仅升级第三位版本号）：

修复插件运行过程中发现的功能性 Bug、逻辑漏洞、数据异常问题；
优化插件细节交互、页面样式、接口响应效率、代码冗余问题；
微调配置参数、修正注释、优化日志输出，无业务功能变更；
小范围兼容适配，未改动插件核心架构和功能。

示例：1.0.0 修复问题后升级为 1.0.1

3.2 次版本号升级（MINOR）

适用场景（第二位版本号+1，修订号归零）：

插件新增业务功能、新增拓展能力、新增配置项、新增接口/页面；
对现有功能进行迭代优化、能力升级，保留原有功能兼容；
框架小幅兼容适配：NocoBase 框架小版本升级（修订号变更），插件出现轻微不兼容，仅需微调代码即可适配，无架构改动。

示例：1.0.1 新增功能后升级为 1.1.0

3.3 主版本号升级（MAJOR）

适用场景（第一位版本号+1，次版本号、修订号归零）：

插件核心架构、底层逻辑、数据结构、存储方式发生重大调整；
插件废弃原有核心功能、调整整体使用逻辑，不兼容旧版本数据或配置；
框架重大兼容适配：NocoBase 框架主版本/次版本大幅升级，插件原有代码体系无法兼容，需要大规模重构、改造核心逻辑才能适配；
插件进行整体重构、改版，功能体系发生颠覆性变更。

示例：1.3.2 架构重构适配新版框架后升级为 2.0.0

4. 框架兼容版本管理规则

4.1 兼容标注要求

所有插件发布时，必须在插件配置文件、版本说明文档中明确标注 适配 NocoBase 框架版本范围，格式规范：

精准适配：适配框架固定版本，如 适配 NocoBase 1.20.0
区间适配：适配框架多个版本，如 适配 NocoBase 1.20.x ~ 1.21.x

4.2 框架不兼容处理规则

当 NocoBase 框架升级后，现有插件出现功能报错、失效、样式错乱、接口异常等不兼容问题时，必须进行插件版本升级，禁止直接覆盖旧版本、不更新版本号的适配方式。
根据框架改动幅度、插件改造工作量，对应升级插件次版本号或主版本号（参考 3.2、3.3 场景规则）。
适配完成后，同步更新插件适配的框架版本范围，清晰标注兼容边界。
旧版本插件保留原有兼容框架版本说明，用于历史环境追溯。

5. 版本初始定义与迭代规范

5.1 初始版本定义

全新开发、首次发布的自研插件，初始版本统一为 1.0.0，禁止使用 0.x.x 测试版本作为正式发布版本。

版本里程碑约定：

0.1.0：新发布，内部测试版本，仅用于内部验证、内部使用，禁止对外正式上架；

0.*.*：迭代内部测试、持续升级迭代，完成功能补齐与问题修复；当插件功能完整、文档齐全、测试通过，具备上架条件时，即可发布正式版；

1.0.0：第一个正式发布版本，代表插件功能稳定，具备对外上架交付条件。

5.2 迭代禁忌规则

禁止无变更、无迭代的空版本升级；
禁止跨版本跳跃升级（如从 1.0.0 直接升级为 1.2.0），迭代需逐段递增；
禁止修改已发布正式版本的版本号，已发布版本永久固化；
禁止不同功能、不同修复内容混用版本升级类型。

5.3 版本更新日志要求

每一次插件版本升级，必须同步更新版本日志，日志需至少包含：

插件版本号
兼容的NocoBase框架版本范围
更新时间
变更类型：新增/修复/变更/不兼容说明
简要变更内容

6. 版本发布与归档规范

插件发布包、源码分支、版本文档必须一一对应版本号，做到版本可追溯、可回滚；
针对不同 NocoBase 框架版本的适配插件，单独归档、标注区分，避免版本混用；
测试环境、生产环境插件版本严格统一，禁止环境间版本不一致；
重大框架适配版本、插件主版本迭代，需单独留存版本适配说明文档。

7. 命名示例

7.1 插件版本迭代示例

迭代场景	插件版本命名	框架适配版本命名
全新插件首次发布	1.0.0	1.21.0
修复Bug，无功能更新、无框架变动	1.0.1	1.21.0
新增功能，适配原框架版本	1.1.0	1.21.0
框架小幅升级，微调代码适配	1.2.0	1.21.5
框架大版本升级，插件重构适配	2.0.0	1.22.0

7.2 代码示例

{
  "name": "@youchaoyun/plugin-data-dictionary",
  "version": "1.21.0",
  "pluginVersion":"1.0.0",
  "main": "dist/server/index.js",
  "displayName": "Data dictionary",
  "displayName.zh-CN": "数据字典",
  "description": "A collection of descriptions of data objects or items in a data model.",
  "description.zh-CN": "对于数据模型中的数据对象或者项目的描述的集合。作者：有巢数智",
  "dependencies": {},
  "peerDependencies": {
    "@nocobase/client": "2.x",
    "@nocobase/server": "2.x",
    "@nocobase/test": "2.x"
  }
}