Dart SDK 分支管理与发布周期全解：从 main 到 stable 的四通道工作流

Dart SDK 分支管理与发布周期全解从 main 到 stable 的四通道工作流【免费下载链接】sdkThe Dart SDK, including the VM, JS and Wasm compilers, analysis, core libraries, and more.项目地址: https://gitcode.com/gh_mirrors/sdk1/sdkDart SDK 采用单主干 三个发布通道的简洁分支模型日常开发集中在main分支功能在验证充分后通过 flag 门控逐步开放最终经dev→beta→stable三个通道逐级发布。本文以仓库文档 docs/Branches-and-releases.md 为核心骨架结合 tools/VERSION、tools/utils.py 及 docs/Cherry-picks-to-a-release-channel.md 等源码级证据完整讲解分支职责、约两个月一轮的发布节奏、cherry-pick 季节的操作流程以及实验性 flag 如何与发布通道协同工作。读完你既能看清整个 SDK 从提交到发布的完整链路也能直接上手执行把修复带到 beta/stable的完整操作。四分支模型一条主干三条发布通道Dart SDK 的分支结构非常简单直接所有日常开发都在main上完成尚未准备就绪的特性统一藏在实验 flag 之后待稳定性充分验证后才默认开启偶尔也会为大型破坏性改动创建临时特性分支。除此之外还有dev、beta、stable三个发布分支负责把代码逐级推向用户。四类分支的职责与约束如下分支来源刷新频率发布产物开发者注意事项main日常开发主干持续每日构建你的 CL 应该落在 maindev从 main 全量推送通常每周两次dev 通道构建不要在 dev 上直接落 CLbeta从 dev 全量推送或 cherry-pick通常每月一次beta 通道构建不要在 beta 上直接落 CLstable从 beta 全量推送或 cherry-pick有发布时stable 通道构建不要在 stable 上直接落 CLmain日常开发分支everyday 开发都在这里进行所有普通 CL 都应落在 main。可以理解为开发者唯一真正打交道的分支。dev由 main 通过全量推送full push填充通常每周两次。除非紧急情况否则不会在 dev 上落 cherry-pick。dev 通道构建由此分支发布。beta由 dev 全量推送填充通常每月一次或通过 cherry-pick 更新。beta 通道构建由此分支发布。stable主发布分支。当某个版本准备好发布时从 beta 全量推送而来或通过 cherry-pick 更新。stable 通道构建由此分支发布。一个需要反复强调的纪律是dev、beta、stable三个分支都不接受直接提交的 CL发布分支的内容只能通过全量推送或 cherry-pick 两条路径进入这从流程上保证了发布内容的可追溯性。发布周期约两个月一轮的稳定化流程Dart SDK 的正常发布周期约为2 个月但这个数字并非承诺——团队会根据稳定性提前或推迟发布。团队并不遵循特性驱动的发布节奏但大型语言特性可能例外为了让所有工具链VM、编译器、分析器等保持同步可能推迟某个版本。完整周期可以拆解为以下阶段日常阶段周期的大部分时间团队持续在main上工作并定期把 main 的绿构建green build全量合并到dev约每周两次。如果在 dev 上快速发现了 bug会再做一次额外的全量推送。稳定化阶段周期最后约 2 周把最新的 dev 版本全量推送到beta进入 beta 通道稳定期。此阶段只允许对 beta cherry-pick 关键修复critical fixes。main 上的开发与 dev 通道的发布照常继续。这一阶段被称为cherry-pick seasoncherry-pick 季节每周会做多批 cherry-pick 并在 beta 通道发布。发布阶段当 beta 通道状态良好looks good时合并到stable并正式发布。补丁维护阶段在 2 个月的周期中基于最新的 stable 版本持续为安全security、崩溃crash、关键 bugcritical bug发布补丁版本。cherry-pick season 中把你的改动带到 beta在 cherry-pick 季节如果你的修复需要进入 beta 通道完整操作流程见 Cherry-picks-to-a-release-channel.md核心步骤概括为先在 main 上落地修复与测试 → 识别 beta/stable 是否受影响 → 在新分支上执行git cherry-pick --edit→ 更新提交信息添加[beta]或[stable]hashtag改写Reviewed-on为Cherry-pick移除不适用于新 CL 的字段→ 填写 Issue description / What is the fix / Why cherry-pick / Risk / Issue link(s) 五段式说明 →git cl upload提交 Gerrit 审批 → 由领域专家与 Dart 团队 lead 评审后提交 commit queuetryjobs 会与 beta/stable 分支上一提交对比测试结果引入回归则失败。版本号如何随周期演进版本号并不是随手改的而是由 tools/VERSION 文件与 tools/utils.py 中的Version类、ReadVersionFile、GetVersion等逻辑共同驱动。当前仓库的 VERSION 文件内容为CHANNEL main MAJOR 3 MINOR 14 PATCH 0 PRERELEASE 0 PRERELEASE_PATCH 0VERSION 文件头部注释完整定义了数字的变化规则新发布周期开始stable 刚发布MINOR1PATCH/PRERELEASE/PRERELEASE_PATCH归 0push-to-trunk周期内首次会同时把PRERELEASE归 0PRERELEASE1PRERELEASE_PATCH归 0cherry-pick 到 trunkPRERELEASE_PATCH1发布 stablePRERELEASE与PRERELEASE_PATCH归 0新的 stable 版本号会排在所有 prerelease 之上stable 通道的 cherry-pickPATCH1。tools/utils.py 中的GetVersiontools/utils.py#L369-L384展示了这些字段如何拼装成最终版本字符串main/be通道 →{major}.{minor}.{patch}-edge.{git_hash}如3.14.0-edge.abcdef1234beta/dev通道 →{major}.{minor}.{patch}-{prerelease}.{prerelease_patch}.{channel}stable通道 → 纯{major}.{minor}.{patch}。而Version.__str__tools/utils.py#L177-L182则定义了语义化版本串的拼接规则。这套机制保证了四个分支上的版本号始终可比较、可排序这正是dev 版本号永远低于未来 stable 版本号这一保证的来源。实验 flag 与分支模型的协同大特性如何安全落地原文档特别强调尚未准备好上线的特性隐藏在 flag 之后待稳定性充分验证后启用。这正是 tools/experimental_features.yaml 的职责所在。从该文件的结构看其help、enabledIn、experimentalReleaseVersion、expired、validation等字段详见文件头部注释与 docs/process/experimental-flags.md一个实验特性会经历如下状态机Disabled刚加入文件时省略enabledIn与expired字段默认关闭可通过--enable-experimentxxx命令行开启Experimental release加入sdk/lib/_internal/allowed_experiments.json白名单并提升experimentalReleaseVersion允许特定库/包默认开启其他用户仍需显式传 flagShipped添加enabledIn字段标记正式发布的 SDK 版本此时 flag 默认开启且无法关闭Retired / Rejected添加expired: true命令行传 flag 会收到警告但工具继续运行条目等待最终从文件中移除。原文档给出了一个典型时序特性在版本 n-1 的 beta 1 公开为实验特性在版本 n 的 beta 1 默认启用在版本 n1 的 beta 1 退役。从当前文件可以看出records、patterns、class-modifiers等已在 3.0.0 默认启用并标记expired: truedot-shorthands3.10.0 启用、native-assets3.10.0 启用、primary-constructors3.13.0 启用等也已走完这条生命周期而macros、augmentations、enhanced-parts等仍处于实验阶段。这个机制正是main 上可以安全地长期保留未完成代码的根基——未完成特性对用户不可见而dev/beta/stable通道的每次构建因此都能保持功能完整且受支持的高质量。实践操作按分支定位版本与频道查看当前分支的版本通道VERSION 文件中的CHANNEL字段即当前分支的发布通道标识。在仓库根目录执行$ git branch --show-current main $ cat tools/VERSION | grep CHANNEL CHANNEL main每个发布分支dev/beta/stable上的 VERSION 文件会各自携带对应的通道标识这正与 tools/utils.py 中GetChanneltools/utils.py#L387-L389读取CHANNEL字段的逻辑对应。把修复带到 stable 的完整流程cherry-pick以 docs/Cherry-picks-to-a-release-channel.md 的操作步骤为基准$ git fetch $ git new-branch --upstream origin/stable cherry # 或 origin/beta $ git cherry-pick --edit $commit $ $EDITOR CHANGELOG.md # stable 必须更新 CHANGELOGbeta 不需要提交信息按以下规则改写示例见原文档[stable] Fix foo crash. Issue description: When attempting to use foo under certain conditions, users are unable to compile. What is the fix: foo is now evaluated at runtime. Why cherry-pick: Users of foo are no longer able to compile to bar. Risk: Low, this fix has landed on the main channel and is tested on the same infrastructure. Issue link(s): https://github.com/dart-lang/sdk/issues/12345678 Cherry-pick: https://dart-review.googlesource.com/c/sdk//12345678要点包括第一行以[beta]或[stable]Gerrit hashtag 开头Reviewed-on改名为Cherry-pick并指向原始 CL删除不再成立的Change-id、Commit-queue、Reviewed-by字段说明必须包含 Issue description / What is the fix / Why cherry-pick / Risk / Issue link(s) 五个要素。CHANGELOG 要求stable 通道的 cherry-pick 必须携带 CHANGELOG.md 条目相关硬性要求见 docs/Gerrit-Submit-Requirements.mdbeta 通道则不需要。若下一个 stable 补丁版本尚未在 CHANGELOG 中建立小节需要新建小节并把补丁号 1如3.0.4→3.0.5且不加发布日期——日期在正式发布时才补上已有发布日期的小节表示已经发布不得再改动。纯基础设施、对用户不可见的改动可通过Changelog-Exempt: ...脚注豁免。随后上传并提交$ git cl uploadCL 需经领域主题专家area subject matter expert与 Dart 团队 lead 双重评审之后作者将其提交到 commit queue。关键保护机制tryjobs 会把测试结果与 beta/stable 分支上的前一提交对比一旦引入回归即失败若必须引入回归、或 try builders 无法在较老的 beta/stable 代码上运行可在 Gerrit 中强制提交... - Submit绕过 commit queue。cherry-pick 依赖仓库中的提交当修复涉及第三方依赖如third_party/pkg/pub时流程变为两步。先在 SDK 检出中定位发布分支上的依赖修订号dart-sdk/sdk/ git checkout beta git pull dart-sdk/sdk/ gclient getdep -r sdk/third_party/pkg/pub a3f8b2fd36ec432450caf907474a02023ef3e44e然后在依赖仓库的克隆中做 cherry-pick 并推送等待镜像同步后通过合并提交把该提交并入依赖的受保护分支防止被 GC最后回到 SDK 检出用tools/manage_deps.dart创建 bump 提交dart-sdk/sdk/ tools/manage_deps.dart bump third_party/pkg/pub --target6d1857c84cfb8a014aefedaf2d453214bf5ddb96 dart-sdk/sdk/ git branch --set-upstream-toorigin/beta dart-sdk/sdk/ git cl upload总结一套面向稳定与速度的工程纪律回顾整个模型可以提炼出 Dart SDK 发布工程的核心设计单一主干多通道发布所有开发集中在maindev/beta/stable只通过全量推送与 cherry-pick 两种受控路径更新杜绝了发布分支的不可控提交。稳定化节奏前置每个周期最后两周专门用于 beta 通道稳定化cherry-pick season把风险控制在发布之前。flag 门控替代特性分支未完成特性以实验 flag 形式长期存在于 main既保证 dev 通道构建的功能完整性又允许大特性跨多个版本持续演进如 null safety、records、macros。版本号机器可读tools/VERSION 与 tools/utils.py 的组合让每个通道的版本号保持单调可排序为发布判断和依赖解析提供了可靠依据。这套机制同时服务于三类人群普通开发者只需知道CL 落在 main实验特性用 flag 尝鲜贡献者需要掌握 cherry-pick 的完整操作与提交信息规范而需要预发布版本的团队则可以根据 dev/beta 通道的构建选择合适的时间窗口。相关细节还可进一步阅读 Cherry-picks-to-a-release-channel.md、Gerrit-Submit-Requirements.md 与 Experimental-Flags.md。【免费下载链接】sdkThe Dart SDK, including the VM, JS and Wasm compilers, analysis, core libraries, and more.项目地址: https://gitcode.com/gh_mirrors/sdk1/sdk创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考