Polaris 多包仓库的 Changesets 变更日志与版本发布指南 前端UI组件【免费下载链接】polaris-react-archiveShopifys Polaris Design System - React implementation (Deprecated)项目地址https://gitcode.com/gh_mirrors/po/polaris-react-archive点击查看免费下载导读本文以 Polaris 设计系统仓库根目录下 .changeset/README.md 为骨架完整讲解这个由 pnpm workspace Turborepo 组织、横跨shopify/polaris-react、shopify/polaris-tokens、shopify/polaris-icons、shopify/polaris-migrator、shopify/stylelint-polaris等多个 npm 包的多包仓库如何使用 Changesets 统一管理 CHANGELOG 与版本发布。读者学完后将能在自己的 feature 分支上熟练运行pnpm changeset正确回答 CLI 的三个版本决策问题包含哪些包、哪些 major、哪些 minor并理解.changeset/config.json的配置语义、changeset 文件的 front matter 结构以及它们如何与changeset version、changeset publish和 Turbo 构建流水线协同工作最终在 CI 中自动生成 Version Packages PR 并发布到 npm。一、为什么用 Changesets多包仓库的统一版本控制1.1 仓库背景一个仓库、多个 npm 包当前仓库以 pnpm workspace 管理多个独立发布的包。根据 pnpm-workspace.yaml 的packages列表共包含以下子包子包目录npm 包名用途polaris-reactshopify/polarisShopify 后台核心 React 组件库当前版本 13.10.1polaris-tokensshopify/polaris-tokens设计令牌9.4.2polaris-iconsshopify/polaris-icons图标库9.3.1polaris-migratorshopify/polaris-migrator升级 codemod 工具1.0.7stylelint-polarisshopify/stylelint-polarisStylelint 校验工具16.0.7polaris-for-vscodeVSCode 扩展编辑器中提供 Polaris 辅助能力polaris.shopify.com站点设计系统文档站这些包之间的依赖关系也很清晰shopify/polaris依赖shopify/polaris-icons与shopify/polaris-tokensshopify/polaris-migrator又依赖shopify/polaris-tokens和shopify/stylelint-polaris。当一次 PR 同时改动多个包时如果靠人工维护各包的 CHANGELOG 与版本号很容易漏改、错改或出现内部依赖版本不匹配。Changesets 正是为这种monorepo 多包发布场景设计的方案开发者只需在 PR 里描述这次改动影响哪些包、属于什么语义化版本级别版本号与 CHANGELOG 的落地交给工具自动完成。1.2 Changesets 在本仓库中的落地位置本仓库的 Changesets 配置集中在 .changeset 目录当前包含三个文件.changeset/README.md给开发者看的操作说明本文主体.changeset/config.jsonChangesets 的全局配置.changeset/loud-rivers-wear.md一个真实存在的待处理 changeset 文件内容是polaris.shopify.com的 patch 级改动。根目录 package.json 中还暴露了与版本发布相关的脚本均通过根目录的 pnpm 调用changeset: changeset新建 changeset 的入口version-packages: changeset version pnpm install --lockfile-only落地版本号与 CHANGELOG并同步锁文件release-packages: pnpm build:release changeset publish构建全部非站点包后发布到 npmbuild:release: turbo run build --filter!polaris.shopify.com用 Turborepo 构建除站点外的所有包。也就是说Changesets 并不是孤立的一个目录而是与仓库的构建、发布流水线深度绑定。二、核心操作运行pnpm changeset添加变更条目2.1 前置约定根据 .changeset/README.md 的说明为你的 PR 添加 CHANGELOG 条目的标准姿势是在你的 feature 分支上运行pnpm changeset然后使用方向键arrow、空格键spacebar和回车键return回答 Changesets CLI 提出的三个问题。整个交互过程是 TUI 式的多选界面不需要手写任何 YAML。2.2 问题一 Which packages would you like to include?按Space键勾选本次改动涉及的包可多选按Enter键进入下一个问题。这一步是改动范围声明本次 PR 改了哪些包就把哪些包勾进来。勾选本身不决定版本级别只决定哪些包的 CHANGELOG 会获得条目。2.3 问题二 Which packages should have a major bump?直接按Enter表示本轮没有破坏性变更进入下一问若本次改动包含破坏性变更如移除组件 API、修改公共接口则用方向键定位到对应包按Space勾选使其在发布时获得major级别升级对应 SemVer 的 X.0.0。2.4 问题三 Which packages should have a minor bump?直接按Enter表示不选择任何 minor 包此时你的改动会自动被归为 patch 级别若本次改动包含向后兼容的新功能新增组件、新增 props、新增 API用上下方向键定位并配合空格键勾选使其获得minor升级对应 SemVer 的 X.Y.0。注意这里的关键设计默认 patch。如果不主动声明 major 或 minorChangesets 会保守地按 patch 处理避免开发者遗漏标记导致意外的大版本提升。CLI 完成后终端会输出类似如下的确认信息 The following packages will be patch bumped: {PACKAGE NAME} {PACKAGE NAME} Please enter a summary for this change (this will be in the changelogs). (submit empty line to open external editor) Summary › {CHANGELOG ENTRY}接下来输入一段面向读者的摘要Summary它会直接进入该包未来的 CHANGELOG。如果直接提交空行Changesets 会打开外部编辑器$EDITOR供你撰写更长的说明。2.5 提交与收尾按 Change Log 内容规范撰写摘要本仓库 README 指向团队维护的 changelog 编写规范核心要求是写清楚对使用者意味着什么而不是复述代码 diff随后commit并push这个生成的 changeset 文件即可。2.6 一个真实示例changeset 文件长什么样运行pnpm changeset后会在 .changeset 目录生成一个随机命名通常是形容词-名词-动词风格的 Markdown 文件。仓库里现成的 .changeset/loud-rivers-wear.md 就是一个标准示例--- polaris.shopify.com: patch --- Updating dux package to 5.0.1其结构非常清晰开头的---包裹部分是front matter每行形如包名: 版本级别声明哪个包要升到什么级别---之后是CHANGELOG 正文即开发者输入的 summary该文件还有未使用的元数据部分如shopify/polaris: minor这种行会被同时保留用于说明内部依赖是否需要跟随升级。正因如此changeset 文件本身就是一个可评审、可回溯的发布意图声明PR reviewer 可以在合并前就确认版本级别是否合理。三、配置解读.changeset/config.json 的每一项语义仓库的 .changeset/config.json 是 Changesets 的全局配置内容如下{ $schema: https://unpkg.com/changesets/config2.0.0/schema.json, changelog: [changesets/changelog-github, {repo: Shopify/polaris}], commit: false, fixed: [], linked: [], access: public, baseBranch: main, updateInternalDependencies: patch, ignore: [], ___experimentalUnsafeOptions_WILL_CHANGE_IN_PATCH: { updateInternalDependents: always } }各字段含义如下配置项值含义与影响$schemachangesets/config2.0.0/schema.json编辑器校验与智能提示用声明配置 schema 版本changelog[changesets/changelog-github, {repo: Shopify/polaris}]指定 CHANGELOG 生成器为 GitHub 风格会生成感谢贡献者 关联 PR 链接的条目并指向目标仓库Shopify/polaris对应根目录 devDependencies 中的changesets/changelog-github^0.5.1commitfalse执行changeset version时不自动创建 git commit将版本落地与提交动作解耦便于人工审查 diff 后再提交fixed[]不启用固定版本组若启用组内包必须一起发布到同一版本linked[]不启用联动版本若启用组内包版本号保持同步递增accesspublic发布到 npm 时使用 public 访问级别适用于公开发布的开源包baseBranchmain以main作为版本计算的基准分支updateInternalDependenciespatch当仓库内包 A 依赖包 B且 B 本次有 minor/major 升级时A 对 B 的版本依赖至少以 patch 级别跟随更新保证安装后内部依赖版本一致ignore[]不忽略任何包___experimentalUnsafeOptions_WILL_CHANGE_IN_PATCH.updateInternalDependentsalways实验性选项内部依赖方如shopify/polaris之于shopify/polaris-tokens只要依赖被升级就无条件更新其依赖声明这些配置与子包 package.json 中的publishConfig是配套的。例如 polaris-react/package.json、polaris-tokens/package.json、polaris-icons/package.json、polaris-migrator/package.json 都声明了publishConfig: {access: public}与access: public一致确保发布时无需交互确认即可公开发布。四、从 changeset 到发布完整的发布工作流4.1 消费 changeset 的两条命令changeset 文件并不会自己生效版本落地与发布由以下命令完成对应根目录 package.json 的脚本pnpm version-packages # 等价于: changeset version pnpm install --lockfile-only pnpm release-packages # 等价于: pnpm build:release changeset publishchangeset version会读取 .changeset 下所有待处理 changeset按 front matter 的声明更新各包 package.json 的 version 字段、追加/合并 CHANGELOG.md并消费掉这些 changeset 文件通常移动到.changeset的历史归档中之后用pnpm install --lockfile-only同步 pnpm-lock.yaml保证锁文件与更新后的版本一致changeset publish则根据新版本号逐个npm publish各包。4.2 版本计算与内部依赖联动从配置可以看出本仓库的发布策略每个 PR 独立产生 changeset互不阻塞版本号在发布前统一计算fixed与linked均为空说明各包版本独立演进互不强制同版本但updateInternalDependencies: patch与updateInternalDependents: always保证内部依赖链shopify/polaris→shopify/polaris-tokens、shopify/polaris-iconsshopify/polaris-migrator→shopify/polaris-tokens、shopify/stylelint-polaris的版本声明始终跟随上游升级避免出现发布后内部依赖还指向旧版本的经典 monorepo 问题。4.3 CI 中的自动发布Version Packages PR仓库的发布文档 documentation/Releasing.md 描述了 Changesets 官方 GitHub Action 在 CI 中的行为每当 PR 合入mainCI 自动创建/更新changeset-release/main分支并打开标题为[Version Packages]的 PR该 PR 始终包含一次最新执行的changeset version结果合入changeset-release/main到main后触发release.yml工作流执行发布发布完成后重建changeset-release/main分支准备下一轮版本。此外documentation/Releasing.md 还介绍了两种补充发布手段Snapshot releases快照发布在 CI 通过的 feature 分支 PR 上评论/snapit即可把当前改动打成带前缀的预发布版本供消费项目临时测试无需真正发布正式版本Prereleasebeta在next分支上执行pnpm changeset pre enter beta进入预发布模式所有 changeset 会被汇总到 [Version Packages (beta)] PR合并后以betadist-tag 发布供大版本含破坏性变更的候选验证。五、写给团队成员的实操清单把上面的内容收敛成一份可执行的清单适用于任何在本仓库提交 PR 的开发者确保当前在 feature 分支且改动已完成运行pnpm changeset问题一Space勾选本次改动的包Enter进入下一问问题二若无破坏性变更直接Enter若有用方向键 Space勾选对应包问题三若无新功能直接Enter自动归为 patch若有勾选对应包在Summary ›处按 CHANGELOG 规范撰写面向使用者的摘要空行可唤起外部编辑器检查生成的 changeset 文件front matter 中的包名与级别、正文摘要commit并push后续由 CI 自动生成 Version Packages PR合并即发布若想提前验证可用/snapit触发 snapshot release。六、常见疑问与注意事项为什么默认是 patch因为 Changesets 的哲学是保守升级只有显式声明 major/minor 才会提升版本级别避免无意的破坏性版本。可以直接手写 changeset 文件吗可以。参考 .changeset/loud-rivers-wear.md 的格式即可但 CLI 能保证包名拼写正确、级别选择正确仍建议用pnpm changeset生成。版本落地与提交是分离的。commit: false意味着changeset version只改文件不自动 commit团队可以在提交前人工审查版本 diff。Node 版本要求。根据根目录 package.json 的engines本仓库要求 Node20.10.0且使用pnpm8.15.5作为包管理器运行 changeset 相关命令前请先满足环境要求。发布前必须构建。仓库的release-packages先执行pnpm build:releaseTurborepo 构建除polaris.shopify.com外的所有包再changeset publish因为发布的是构建产物如shopify/polaris的build/目录见 polaris-react/package.json 的files字段。结语Changesets 为 Polaris 这样的多包 monorepo 提供了一套声明式 自动化的版本治理方案开发者只需在 PR 中回答三个问题、写一段面向使用者的摘要剩下的版本号计算、CHANGELOG 生成、内部依赖联动、npm 发布与 CI 自动化都由 .changeset/config.json 与根目录 package.json 中的脚本协同完成。理解这一套机制不仅能让你在 Polaris 仓库中顺畅提交变更也能迁移到任何使用 Changesets 的 pnpm monorepo 项目中。赞分享前端UI组件【免费下载链接】polaris-react-archiveShopifys Polaris Design System - React implementation (Deprecated)项目地址https://gitcode.com/gh_mirrors/po/polaris-react-archive点击查看免费下载相关推荐fail2ban 异步通信服务器asyncserver源码解析从 Unix Socket 到请求处理的完整链路fail2ban 异步通信服务器asyncserver源码解析从 Unix Socket 到请求处理的完整链路 本文以 doc/fail2ban.serv前端UI组件Phoenix 项目中的 JavaScript 数组比较优化先检查长度Early Length Check实战指南Phoenix 项目中的 JavaScript 数组比较优化先检查长度Early Length Check实战指南 本文聚焦 Vercel React B开发工具CLIchangesets/types 类型包深度解析changesets 版本管理与变更日志生态的类型基石changesets/types 类型包深度解析changesets 版本管理与变更日志生态的类型基石 导读 changesets/types 是整个 c开发工具CLI上一篇如何快速部署A-Ops面向初学者的5分钟安装教程下一篇rpmdepsearch性能调优如何加速大规模软件包依赖分析创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考