Mastra 的 Changeset 工作流：用仓库自带 CLI 为每个包生成可发布级 Changelog

Mastra 的 Changeset 工作流用仓库自带 CLI 为每个包生成可发布级 Changelog【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra这篇指南基于 Mastra 仓库中的 changeset 命令文档讲清楚 Mastra 单仓库monorepo是如何围绕 Changesets 工具链管理版本与 Changelog 的如何为有变更的包创建 changeset 文件、如何选择 major/minor/patch 版本递增类型、如何撰写面向开发者的变更说明以及如何把跨包改动拆分成多个逻辑独立的 changeset 文件。读完你能掌握pnpm changeset这条命令的完整用法、参数细节以及其底层 CLI 实现变更检测、bump 决策、changeset 文件写入的源码级原理。Changeset 在 Mastra 中的定位Mastra 是一个由几十个 npm 包组成的 monorepomastra/core、mastra/memory、mastra等分布在 packages、stores、voice 等目录下。这些包的版本发布采用 Changesets 工作流changeset 的目标是生成 changelog。每个包有自己的 changelog发布时各包的 changelog 会被合并进单次 release 的统一 changelog因此每个有变更的包必须拥有自己独立的 changeset 文件——这是保证各包 changelog 准确的前提仓库根目录 package.json 中定义了入口脚本changeset: pnpm --filter internal/changeset-cli start,即pnpm changeset会转交给仓库自研的内部 CLI 包 internal/changeset-cli注意它与 npm 上游的changesets/cli是两个不同的工具根目录 devDependencies 里同时依赖了changesets/cli用于其他发布环节而本文讲的pnpm changeset走的是内部定制版本。该内部 CLI 的 启动脚本 为tsx --env-file./.env.dev src/index.ts用 tsx 直接以 TypeScript 源码方式运行。创建 Changeset 的 CLI 用法对每个有变更的包运行一次 CLI指定该包合适的版本递增类型与说明pnpm changeset -s -m your changeset message (--major | --minor | --patch) pkg-name每次运行会为该包创建一个独立的 changeset 文件。典型示例# 单包补丁级修复 pnpm changeset -s -m Fixed a race condition in the session manager --patch mastra/core # 多个包同一逻辑改动重复传 flag pnpm changeset -s -m Added support for custom embedding providers --minor mastra/memory --minor mastra # 破坏性变更 pnpm changeset -s -m Removed deprecated createTool signature --major mastra/core参数说明参数说明-s/--skipPrompt非交互式运行要求至少提供--major、--minor、--patch之一自动化场景必需-m message/--message messagechangeset 说明文案必需--major pkg-name指定做 major 版本递增的包--minor pkg-name指定做 minor 版本递增的包--patch pkg-name指定做 patch 版本递增的包两点注意bump 类型必须显式为每个包指定非补丁级变更用--major或--minor不要依赖默认值多个包通过重复 flag指定例如--minor mastra/core --minor mastra。从源码看这套参数解析位于 parseArguments它用mri解析命令行参数major/minor/patch均被声明为 string 类型并在解析后用ensureArray归一化为数组这正是重复 flag 传多个包能生效的原因。交互模式不带-s时CLI 进入交互式流程getVersionBumps 中的promptForVersionBumps先自动检测相对origin/main远程不可用时回退到本地main有变更的公开包作为候选预选通过clack/prompts的多级多选让你确认包含哪些包、哪些做 major、哪些做 minor未被指定为 major/minor 的候选包自动落到 patch未提供-m时打开默认编辑器撰写说明getChangesetMessage创建 changeset 文件后打印 Summary并自动处理 peer dependencies 的联动更新见下文。版本递增类型patch向后兼容的 bug 修复minor向后兼容的新功能major不向后兼容的破坏性变更。对应语义版本号即0.0.x/0.x.0/x.0.0的递增位与内部 CLI 的 README 中 Version Bump Logic 一节一致。底层执行流程从变更检测到文件写入内部 CLI 的 入口 main 函数 串起完整调用链理解它有助于知道命令每一步在做什么1. 变更包检测detectChangedPackages调用 getChangedPackages底层使用changesets/git的getChangedPackagesSinceRef以origin/main为基准 ref、**/*为文件匹配模式找出变更目录再与公开包列表getPublicPackages即排除private: true的包取交集。若没有任何变更包命令直接以 No changed packages detected. Exiting. 退出。2.--skipPrompt的前置校验非交互模式下若未提供任何 bump flagCLI 会报错Please provide at least one of --major, --minor, or --patch flags when using --skipPrompt.并退出保证自动化脚本不会静默产生空 changeset。3. 组装版本递增输入prepareVersionBumpInputs这里有一个关键的默认行为patch列表 自动检测到的所有变更包∪ 显式--patch参数再去掉已列入 major/minor 的包。也就是说只要你的分支改了某个包却没显式指定它的 bump 类型它会被默认归入 patch——这与文档要求显式指定 bump 类型形成互补交互模式和 CI 场景下建议显式声明避免重要功能被当成补丁发布。4. 写入 changeset 文件createCustomChangesetcreateCustomChangeset 把{包名: bump类型}映射为 releases 列表调用changesets/write的writeChangeset以仓库根目录config.ts 中rootDir指向 monorepo 根为目标、开启 prettier 格式化生成带 YAML frontmatter 的 markdown 文件即标准 Changesets 文件格式frontmatter 列出包名与 bump 类型正文即-m传入的说明。5. peer 依赖联动与 Summary版本 bump 确定后updatePeerDependencies会扫描 monorepo 中依赖这些包的 peerDependencies 并联动更新版本范围最后通过getSummary打印每个包的 bump 类型与 peer 依赖变更摘要。说明文案Message撰写规范Changeset 说明会原样进入最终发布的 changelog读者是其他开发者。仓库文档给出了明确的撰写守则完整继承如下目标读者是开发者。写短而直接的句子避免 commit message 风格、技术黑话和缩写使用行动导向动词Added、Fixed、Improved、Deprecated、Removed避免 Update code、Miscellaneous improvements、Bug fixes 这类空泛表述突出结果最终用户能看到什么变化不要聚焦内部实现细节相关时附上 issue 或 PR 链接作为上下文若变更是破坏性变更或新功能必须提供代码示例示例应展示公共 API 的用法before/after不要展示内部实现细节的代码保持格式易读、可扫读。必要时用要点或多段落组织用加粗文本作为小节标题不要用 markdown 标题对较大的实质性变更还应回答变更背后的 Why。跨包改动如何拆分 Changeset 文件当一次改动横跨多个包例如mastra/core、mastra/memory、mastra共 3 个包且各包改动性质不同时必须创建多个 changeset 文件否则会把不同性质的变更混进本不该包含它们的 changeset 里。拆分方法先判断改动中存在哪些逻辑分组然后对每个分组运行一次 CLI、选择该分组对应的包。文档给出的判断示例某主功能主要落在mastra/memory而mastra/core和mastra只有配套支撑性改动。那么mastra/memory应当拥有自己独立的 changeset与另外两个包分开——对主功能跑一次 CLI 指定mastra/memory再对支撑改动跑一次 CLI 指定其余包。反模式警示原文档明确要求避免一个 changeset 文件里堆多个包frontmatter 含多个包的超长 changeset 是反模式它会导致多个包的 changelog 都出现同一条冗长条目。若改动涉及多个包通常其中一两个主包承载了大部分变更应以它们为主体单独成文。小结环节命令/机制源码位置入口脚本pnpm changesetpackage.json 的scripts.changeset参数解析与主流程-s/-m/--major/--minor/--patchsrc/index.ts变更包检测对比origin/main找变更的公开包src/git/getChangedPackages.tsbump 决策与默认 patch显式 major/minor其余变更包默认 patchsrc/changeset/getVersionBumps.ts文件写入writeChangesetchangesets/writesrc/changeset/createCustomChangeset.tspeer 依赖联动updatePeerDependenciessrc/versions/updatePeerDependencies.ts一句话工作守则每次运行 CLI 只服务一个逻辑变更组显式指定每个包的 bump 类型写面向开发者、突出结果、必要时带 API before/after 示例的说明——这样每个包的 changelog 才能在发布时自动组合出准确、可扫读的版本记录。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考