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

Yii 2 版本号规约全解析Semantic Versioning 变体、分支策略与发布节奏【免费下载链接】yii2Yii 2: The Fast, Secure and Professional PHP Framework项目地址: https://gitcode.com/gh_mirrors/yi/yii2Yii 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 大版本当前为 2x大版本号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 这种量级才会发生的、大约每 35 年一次的大版本跳跃。2.X.0大版本Major发布2.X.0是允许破坏后向兼容性BC breaking的大版本发布包含大的功能增量和可能破坏 BC 的变更。升级路径不一定轻松但官方会提供完整的升级指南对应仓库中的UPGRADE-2.X.md文件。其典型特征如下特征说明主要内容新功能与 bug 修复为主来源合并自各补丁版本的小功能增强与 bug 修复BC 破坏可能包含必须记录在UPGRADE-2.X.md文件中发布周期大约 12 个月或更长预发布必须经过2.X.0-alpha→2.X.0-beta→2.X.0-rc阶段宣传需要重大的新闻发布与市场推广投入预发布序列alpha/beta/rc的存在意味着大版本在正式稳定之前会先以多个候选版本接受社区测试与反馈这一点与 Semantic Versioning 对预发布版本pre-release的约定一致。2.x.Y小版本Minor发布2.x.Y小版本是**几乎后向兼容mostly BC-compatible**的发布。理想情况下只包含不影响后向兼容的变更但现实中很难做到 100% 兼容因此凡是例外都会被记录在 framework/UPGRADE.md 中——该文件正是 Yii 2.0 全系列的累计升级说明。特征说明主要内容bug 修复与功能增强为主BC 承诺必须几乎后向兼容允许极少数例外并记录于UPGRADE.md发布周期大约 12 个月预发布不需要 alpha、beta、RC合并回主分支必须持续进行至少每周人工合并一次回master宣传伴随新闻公告项目官网同步更新文档特别强调了一个实践动机由于2.0.x系列发布频率较高团队会把一些小功能增强也带进小版本中让用户更早用上新特性而不是非要攒到大版本才放出。2.x.y.Z补丁Patch发布2.x.y.Z补丁版本是只含 bug 修复、必须 100% 后向兼容的发布。它不发布新闻公告、不更新官网除非包含重大或安全问题修复且发布流程基本自动化。特征说明主要内容仅 bug 修复不含功能BC 承诺必须 100% 后向兼容唯一例外是安全问题的修复可能被迫破坏 BC发布周期大约 12 周预发布不需要 alpha、beta、RC合并回主分支发布时必须合并回master仅 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 的分支策略是其版本规约的重要配套规则如下master分支当前稳定大版本的开发分支现阶段承载2.0.x系列版本的持续开发。每个大版本在以其版本号命名的分支上开发例如2.1。也就是说新大版本的预发布与正式发布都发生在这个功能分支上而不是直接在master上完成。维护分支的创建时机当新大版本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开发版本。补丁版本标记为补丁发布创建2.x.y.z标签与2.x.y分支对于2.x.y.0这类补丁号为 0 的版本0会被省略例如2.0.5标签而不是2.0.5.0。合并回流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 --version2.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.zz0时可省略明确区分大/小/补丁三个层级二是为小版本保留了几乎兼容、极少数例外记录在案的弹性空间为补丁版本保留了安全问题可破例的条款三是用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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考