Topcoat Release Flow 揭秘：release-plz、CHANGELOG 与多 crate 版本联动

Topcoat Release Flow 揭秘release-plz、CHANGELOG 与多 crate 版本联动【免费下载链接】topcoatA batteries-included framework for building web apps项目地址: https://gitcode.com/GitHub_Trending/top/topcoatTopcoat 是一个功能完备batteries-included的 Rust 服务端渲染 Web 框架由 32 个相互依赖的 crate 组成。那么它是如何做到一次发布、全体同步的答案是仓库根目录的 release-plz.toml 加一套精心设计的版本组策略。本文带你完整拆解这套发布流程背后的每一个关键决策 一、为什么选 release-plz多 crate 的 Rust 工作区发布最大的痛点是版本容易漂移。几十个 crate 如果各自维护版本号和 CHANGELOG稍不注意就会出现topcoat是 0.8.0、topcoat-router却是 0.7.9 的尴尬局面。release-plz 是一个自动发布工具它能从提交历史自动生成 CHANGELOG、按语义化版本推导版本号、创建发布 PR并推送 tag 触发 crates.io 发布。Topcoat 把它作为唯一发布入口人工零干预。二、核心配置拆解一份 release-plz.toml 里的 4 个关键决策打开 release-plz.toml几乎每一段注释都在避坑。我们按重要程度逐个看1. 默认不发布可发布 crate 显式举手release false全局默认release false每个可发布 crate 再用[[package]]段声明release true。这不是为了省事而是为了绕开一个隐藏 bugrelease-plz 的 release-order 阶段会对所有工作区成员做拓扑排序而 examples/benchmarks 里存在 facade ↔ 子 crate 的循环依赖引用会被误报为circular dependency。默认关闭后这些不可发布的成员直接被排除在流程之外见 release-plz.toml#L9-L16 的注释。2. 一个版本只打一个 tag版本组策略git_tag_enable false git_release_enable false全局关闭 tag 和 release然后只让 facade cratetopcoat重新打开配置项作用version_group topcoat全部 32 个 crate 共享同一个版本号git_tag_name v{{ version }}tag 只按 Topcoat 整体版本打如v0.8.0git_release_name v{{ version }}每个版本只有一个 GitHub Release也就是说不存在topcoat-router-v0.8.0这种 per-crate 的 tag用户永远只需关注v0.8.0这一个版本号 ️3. CHANGELOG 归集facade 一份覆盖整个工作区topcoatfacade 的changelog_include列出了其余全部 31 个 craterelease-plz.toml#L35-L67。效果是主 CHANGELOG 记录的是整个项目的变更而不是只记录crates/topcoat目录下的提交。对比两个文件就能看出差异crates/topcoat/CHANGELOG.md —— 聚合视图包含*(runtime)*、*(cli)*、*(ui)*等所有 crate 的条目crates/topcoat-router/CHANGELOG.md —— 子 crate 视图条目是主文件的子集4. 发布 PR 自动化参数git_release_draft true pr_draft true pr_labels [release] release_always truerelease-plz 发现有新提交时会自己开一个带release标签的草稿 PRCI 只在release PR 合并或手动触发时执行真正的发布作业release-plz.toml#L1-L7 的注释。三、多 crate 版本联动的底层机制workspace 版本号打开根 Cargo.toml#L74-L84所有 crate 的版本号都来自同一处[workspace.package] version 0.8.0每个子 crate如 crates/topcoat-router/Cargo.toml只写version.workspace true从不自己维护数字。配合 release-plz 的version_group就形成了**改一处、全体升级**的联动release-plz 分析提交历史决定新版本号只修改workspace.package.version这一个字段打包发布时所有 crate 自动拿到新号码四、一个隐蔽的循环依赖陷阱及解法facadetopcoat依赖全部子 crate子 crate 又用 facade 做 dev-dependency跑测试时用完整框架。如果给这个 dev-dependency 带上版本号cargo 在打包子 crate 时就会去 crates.io 解析topcoat ^0.8.0——可发布顺序上子 crate 先于 facade 发布届时 crates.io 上根本还没有这个新版本发布必然失败。解法写在 Cargo.toml#L109-L117 的注释里facade 只声明path、不带 version。Cargo 对纯路径的 dev-dependency 在发布时会直接丢弃从而绕开了这个 facade ↔ 子 crate 的循环。这也是为什么注释特别强调请勿在此加版本号。五、CHANGELOG 从哪来Conventional Commits 是命脉Topcoat 的 CHANGELOG 完全由提交信息驱动。按 CONTRIBUTING.md 的约定PR 标题遵循 Conventional Commits 格式fix(router): isolate request panics由于 PR 一律squash 合并标题就是最终提交信息release-plz 直接据此推导版本提交类型版本行为feat(...)minor 升级0.7.0 → 0.8.0fix(...)patch 升级0.6.1 → 0.6.2带!或BREAKING CHANGE脚注major 升级且必须写明迁移说明scope 一般是被改动 crate 去掉topcoat-前缀后的名字这也正是 CHANGELOG 里*(router)*、*(runtime)*前缀的来源CONTRIBUTING.md#L93-L105。CHANGELOG 本身采用 Keep a Changelog 格式[Unreleased]段随 PR 持续累积发布时 release-plz 把它固化为带日期和版本链接的正式条目例如 0.8.0 的条目里能清楚看到 breaking change 被[**breaking**]显式标注crates/topcoat/CHANGELOG.md#L10-L23。六、一次完整发布的全流程把上面所有环节串起来一次 Topcoat 版本的诞生是这样的日常 PR 合入 mainConventional Commits │ ▼ release-plz 检测到新提交 │ 分析 feat/fix/breaking → 推导版本号 ▼ 自动开出草稿 Release PR ├─ 更新 workspace.package.version所有 crate 联动 ├─ 更新各 crate 的 CHANGELOG.md └─ 打 release 标签 │ ▼ 维护者 Review 后合并该 PR │ ▼ CI 的 release 作业执行仅此 PR 合并或手动触发时才跑 │ ▼ 打 tag v{{ version }} → 创建 GitHub Release │ 正文即 facade 聚合的 CHANGELOG ▼ crates.io 上 32 个 crate 同版本号上架关键细节CI 特意限定只在 release PR 合并时运行发布作业所以 release-plz 自己不需要再校验提交来源配置可以写得更简洁。七、这套方案对普通 Rust 项目的启发版本组 workspace 版本号多 crate 项目让所有 crate 共享workspace.package.version用version_group保证它们永远同版本用户心智成本最低默认不发布 显式 opt-in把不可发布成员挡在拓扑排序之外同时把哪些能发变成一眼可见的清单CHANGELOG 靠提交规范生成Conventional Commits squash merge让写好 PR 标题成为唯一的额外成本循环依赖要提前想清楚facade 带版本号依赖会直接卡死发布顺序纯路径 dev-dependency 是干净的解法这套机制下Topcoat 从 0.6.0 到 0.8.0 的密集迭代crates/topcoat/CHANGELOG.md 可见不到一个月的节奏全程无需人工改任何版本号——这大概就是batteries-included发布体验的完整打开方式 【免费下载链接】topcoatA batteries-included framework for building web apps项目地址: https://gitcode.com/GitHub_Trending/top/topcoat创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考