企业官网建设流程全解析

Yii 2 版本号规约全解析：Semantic Versioning 变体、分支策略与发布节奏

【免费下载链接】yii2Yii 2: The Fast, Secure and Professional PHP Framework项目地址: https://gitcode.com/gh_mirrors/yi/yii2

Yii 2 框架在长期演进中形成了一套自成一体的版本管理规范：它基于 Semantic Versioning（语义化版本）做了务实调整，以2.x.y.z四位版本号区分大版本、小版本与补丁发布，并配套了master主分支 + 版本号命名分支 + 维护分支的完整分支策略。本文基于仓库 docs/internals-ja/versions.md（英文原版见 docs/internals/versions.md）系统讲解这套规约的每一个细节，并结合 framework/BaseYii.php 中的版本号实现、framework/composer.json 中的 branch-alias 配置以及 framework/UPGRADE.md 升级指南，说明版本策略在真实代码库中的落地方式。读完本文，你将能准确识别 Yii 2 各类版本号的含义、理解各分支之间的演进关系，并掌握框架与扩展、应用模板之间相互独立的发布节奏。

版本号格式：2.x.y.z与省略规则

Yii 2 的版本号采用2.x.y.z四段格式：

• 2：主版本号，即 Yii 大版本（当前为 2）；
• x：大版本号（major），对应文中的2.X.0系列；
• y：小版本号（minor），对应2.x.Y系列；
• z：补丁号（patch），对应2.x.y.Z系列。

一个重要的实用规则是：当z为0时，该段可以省略。也就是说，2.1.0和2.1指的是同一个版本，tag 也统一按省略写法生成（见下文"分支与标签规约"）。这也是为什么你在文档、composer 依赖声明中经常看到2.0、2.1这类两位版本号的原因。

在代码层面，当前框架版本号实际定义在 framework/BaseYii.php 的Yii::getVersion()中：

public static function getVersion() { return '2.0.56-dev'; }

注意这里的-dev后缀：它表示当前仓库快照是2.0.56正式版之前的开发状态，对应版本策略中"从master分支持续开发、随时可能发布下一个小版本"的定位。运行中的 Yii 应用可以通过Yii::getVersion()在运行时读取该字符串。

文档还特别说明：未来可能出现的 Yii 3 不在本文讨论范围内。预计它相对 2.0 的关系会像 2.0 相对 1.0 一样，属于依赖外部技术重大演进（例如 PHP 从 5.0 升级到 5.4 这种量级）才会发生的、大约每 3～5 年一次的大版本跳跃。

2.X.0：大版本（Major）发布

2.X.0是允许破坏后向兼容性（BC breaking）的大版本发布，包含大的功能增量和可能破坏 BC 的变更。升级路径不一定轻松，但官方会提供完整的升级指南（对应仓库中的UPGRADE-2.X.md文件）。其典型特征如下：

预发布序列（alpha/beta/rc）的存在意味着：大版本在正式稳定之前，会先以多个候选版本接受社区测试与反馈，这一点与 Semantic Versioning 对预发布版本（pre-release）的约定一致。

2.x.Y：小版本（Minor）发布

2.x.Y小版本是**"几乎后向兼容"（mostly BC-compatible）**的发布。理想情况下只包含不影响后向兼容的变更，但现实中很难做到 100% 兼容，因此凡是例外都会被记录在 framework/UPGRADE.md 中——该文件正是 Yii 2.0 全系列的累计升级说明。

文档特别强调了一个实践动机：由于2.0.x系列发布频率较高，团队会把一些小功能增强也带进小版本中，让用户更早用上新特性，而不是非要攒到大版本才放出。

2.x.y.Z：补丁（Patch）发布

2.x.y.Z补丁版本是只含 bug 修复、必须 100% 后向兼容的发布。它不发布新闻公告、不更新官网（除非包含重大或安全问题修复），且发布流程基本自动化。

"仅 bug 修复、100% 后向兼容"与 Semantic Versioning 对 patch 版本的严格定义完全一致，但 Yii 为安全问题保留了"必要时破坏 BC"的显式例外条款——这是安全优先于兼容性的务实取舍。

后向兼容（BC）的细化约定

版本策略中反复强调"保持 2.0.x 后向兼容"是团队内部多次强调的重要目标，但文档也坦诚：这只是一个理想计划，现实世界中难以完全做到。关于什么算 BC、什么不算 BC 的详细判定标准，见同目录下的 docs/internals-ja/bc.md（英文原版见 docs/internals/bc.md）。

这份 BC 文档以大量表格形式给出了"使用场景"与"开发场景"两类清单。其核心精神可以概括为以下几点：

• 接口与类的公开契约：接口的类型提示、方法调用、接口实现、类的扩展、公共属性访问与公共方法调用等一律视为 BC；新增属性/方法在"类扩展"场景下则被视为不兼容（因为子类可能已占用同名成员）。
• 方法签名变更：为已有方法追加"带默认值的参数"通常兼容；而删除参数、改变参数类型、移除默认值、为参数新增类型提示、改变返回值类型等操作大多被视为不兼容。
• 可见性与修饰符：降低方法/属性的可见性、把类改为final、把类改为abstract均属不兼容；删除构造函数、改变常量值（除非是可能被序列化的对象）也属不兼容。
• 隐私边界：通过反射（reflection）调用私有方法或访问私有属性被视为不兼容——这意味着即使是"私有"成员，框架也会注意保持其行为稳定。

这份清单本质上就是 Yii 团队在评审 Pull Request、决定某个改动应该进入小版本还是大版本时的操作手册，也是UPGRADE.md中逐条记录的变更为什么会被归类为"可能破坏应用"的依据。

分支规约：master、版本分支与维护分支

Yii 2 的分支策略是其版本规约的重要配套，规则如下：

1. master分支：当前稳定大版本的开发分支，现阶段承载2.0.x系列版本的持续开发。
2. 每个大版本在以其版本号命名的分支上开发，例如2.1。也就是说，新大版本的预发布与正式发布都发生在这个"功能分支"上，而不是直接在master上完成。
3. 维护分支的创建时机：当新大版本2.n准备就绪时，从master切出一个命名为2.(n-1).x的维护分支。举例来说，当2.1.0作为稳定版发布并转入master上继续开发后，会创建2.0分支来维护 2.0 系列。这个命名模式对应 Composer 的 branch naming schema（即分支名2.0会被 Composer 识别为2.0.x-dev开发版本）。
4. 补丁版本标记：为补丁发布创建2.x.y.z标签与2.x.y分支；对于2.x.y.0这类补丁号为 0 的版本，0会被省略（例如2.0.5标签而不是2.0.5.0）。
5. 合并回流：2.n.x维护分支上的改动会被持续合并回master，保证主分支始终包含各维护分支的全部修复。

这套策略的最终效果正如 docs/internals-ja/versions.md 中的分支示意图所示：master主干持续向前推进，各版本分支从主干上分叉、承载对应大版本的维护工作，补丁分支再进一步细分，整个提交历史呈现典型的多分支演进形态。

在仓库配置中可以看到该策略的直接证据：framework/composer.json 中声明了：

"extra": { "branch-alias": { "dev-master": "2.0.x-dev" } }

这条配置的含义是：当 Composer 安装dev-master分支代码时，会将其视为2.0.x-dev开发版，从而允许依赖声明"yiisoft/yii2": "~2.0.0"之类的约束直接匹配主分支代码。这正是"master是当前稳定大版本（2.0.x）开发分支"这一分支规约在包管理层面的落地。对照 docs/internals-ja/release.md 中关于发布2.1.0大版本的步骤描述：从master创建2.0维护分支后，还需要把master的 branch-alias 更新为2.1.x-dev，可见该配置是随大版本演进同步调整的。

发布节奏：框架、扩展与应用模板各自独立

版本策略的最后一部分澄清了 Yii 生态中不同组件的发布关系：

• 框架（core framework）与官方扩展（official extensions）彼此独立发布，因此框架与扩展的版本号不一致是完全正常的现象——例如框架是2.0.56时，某个扩展可能还停留在2.1.4。
• 应用模板（Application Templates，即 basic / advanced 模板）总是与框架同步发布。这一点在 docs/internals-ja/release.md 的发布命令中也得到印证：发布框架时需要依次执行release framework、release app-basic、release app-advanced三个命令，而扩展只需单独执行release redis之类的单条命令。
• 上文描述的所有发布周期只适用于核心框架。扩展是按需（on demand）发布的：一个长期没有任何 bug 修复或功能增强的扩展，完全可能在很长一段时间内不产生新版本。

与发布自动化流程的衔接

版本规约并不是停留在纸面上的文档，它与仓库中的自动化发布工具直接关联。如 docs/internals-ja/release.md 所述，框架仓库内置了release控制台命令用于执行发布流程，例如：

./build/build help release # 查看 release 命令的帮助 ./build/build release/info --update # 获取框架与各扩展的版本/标签概览 ./build/build release framework # 发布框架（含应用模板） ./build/build release redis --version=2.1.0 # 用 --version 指定发布指定扩展的特定版本

其中--dryRun选项可以在不产生任何提交与标签的前提下预演发布过程。这套工具的版本处理逻辑（默认基于当前检出分支发布新的小版本、通过--version覆盖为2.1.0、2.1.0-beta等）正是对本文所述"小版本无需预发布、大版本需要 alpha/beta/rc"策略的程序化实现。

升级实操：小版本与补丁版本的应用侧升级

对普通应用开发者而言，版本规约最终落到"如何升级"这件事上。框架仓库的 framework/UPGRADE.md 开头给出了标准做法：常规升级只需更新composer.json中的依赖约束后执行composer update。

# 升级到指定小/补丁版本（示例：2.0.10） composer require "yiisoft/yii2:~2.0.10" --update-with-dependencies # 或只更新指定包，避免牵动其他依赖 composer update yiisoft/yii2 yiisoft/yii2-composer bower-asset/inputmask

由于小版本"几乎后向兼容"、补丁版本"100% 后向兼容"的承诺，这类升级通常是无痛的；只有升级说明中明确标注的例外情况（会破坏 BC 的极少数变更）才需要开发者手工调整代码。这也正是 Yii 把"升级注意事项"统一累积记录在 framework/UPGRADE.md（大版本则对应UPGRADE-2.X.md）中的原因——文档开头即提醒读者：升级说明是累积式的，从 A 版本升级到 C 版本时，需要依次遵循 A 与 B 之间的全部注意事项。

总结

Yii 2 的版本规约是一套在语义化版本基础上为现实演进做了三项务实修正的规范：一是用四位版本号2.x.y.z（z=0时可省略）明确区分大/小/补丁三个层级；二是为小版本保留了"几乎兼容、极少数例外记录在案"的弹性空间，为补丁版本保留了"安全问题可破例"的条款；三是用master+ 版本号分支 + 维护分支 + 持续合并回流的分支策略，支撑框架长达十余年的多版本并行维护。理解这套规约，无论是作为使用者判断composer依赖约束与升级风险，还是作为贡献者理解 docs/internals-ja/bc.md 的 BC 判定清单、参与 docs/internals-ja/release.md 描述的发布流程，都能事半功倍。

关联文档： docs/internals-ja/versions.md ｜ 英文原版：docs/internals/versions.md ｜ 版本号实现：framework/BaseYii.php ｜ 分支别名配置：framework/composer.json ｜ 升级指南：framework/UPGRADE.md

【免费下载链接】yii2Yii 2: The Fast, Secure and Professional PHP Framework项目地址: https://gitcode.com/gh_mirrors/yi/yii2