Carbon Design System 版本发布全流程解析从 prerelease 到 stable 的时间驱动发布指南【免费下载链接】carbonA design system built by IBM项目地址: https://gitcode.com/GitHub_Trending/carbo/carbon本文以 IBM Carbon Design System 仓库monorepo中的 docs/release.md 为核心系统讲解其时间驱动的版本发布模型包括每两周一次的minor稳定版、提前数日发布的preminor/prerelease候选版以及按需发布的patch安全与缺陷修复版。你将掌握完整的手动发布操作序列Version Workflow → 打 tag → Release Workflow → npm dist-tag 提升、v10 旧版本维护流程、手动 patch 发布方法以及常见故障的排障手段同时本文结合仓库内 .github/workflows/version.yml、.github/workflows/release.yml、actions/promote/index.js、lerna.json 等源码与配置深入解释每个步骤背后的自动化原理。发布模型概述为什么是时间驱动Carbon Design System 采用**时间驱动time-based**而非攒够功能再发的发布模型规则非常简单每两周发布一个稳定的minor版本例如v11.2.0。完整的发布节奏记录在项目的 Release Radar 发布日历中。每次minor发布前几天先发布一个 prerelease预发布版。这个版本提供了一个集成窗口integration window让产品团队在稳定版正式发布前能够提前集成并验证这些改动。patch版本按需发布用于承载安全修复和缺陷修复不遵循固定排期。这一模型的核心价值在于既保证了发布节奏的可预期性每两周一次 minor又通过 prerelease 给下游产品留出充分的测试缓冲从而降低稳定版发布引入破坏性变更的风险。发布团队release lead 与 sidekick每一周的发布由**发布团队Release Team**协调完成团队由两名成员组成Release lead发布负责人负责管理发布本身包括测试Testing、发布Publishing、支持Support三大环节并在适当时候指导 sidekick 理解并跑通整个发布流程。Release sidekick发布搭档如果是第一次进入发布团队首要任务是学习如何运行发布流程同时协助 lead 完成测试、发布、支持等各项工作。两人配合共同保证发布流程的稳定执行也起到知识传递的作用。发布流程总览四个检查点一次完整的发布周期包含四个检查点检查点说明Prerelease预发布发布一个预发布版用于在稳定化之前测试发布候选Stable release稳定发布将 prerelease 提升为稳定版通过 npm 包对外可用Post release发布后为最新稳定版提供支持处理因提升到稳定版而产生的问题Previous release旧版本发布判断 v10 是否有新改动需要发布如有则发布v10 已于 2024-09-30 停止支持下面按检查点逐一展开实际操作步骤并标注每一步背后对应的自动化配置。Prerelease 预发布流程预发布发生在每个 sprint迭代的最后一个周一。此时发布团队需要执行以下操作手动触发 Version Workflow对应仓库中的 .github/workflows/version.yml让 Lerna 自动为所有包生成预发布版本号。该工作流通过workflow_dispatch暴露了两个必填输入见 .github/workflows/version.yml#L8-L23type发布类型可选值为minor、preminor、prerelease默认preminortag本次发布对应的 tag 名称例如v11.2.0-rc.0。指定preminor作为发布类型如果是发布下一个 prerelease则指定prerelease。提供本次发布的 tag。例如上一个版本是v11.1.0那么本次预发布的 tag 就是v11.2.0-rc.0可用仓库 tags 列表确认上一个版本的 tag。审查并批准该工作流自动生成的 Pull Request。该 PR 由peter-evans/create-pull-request动作创建分支名为release/tag提交信息与标题均为chore(release): tag见 .github/workflows/version.yml#L68-L82。等待 PR 被合并文档中明确用 强调此步骤不可跳过。合并后将上游最新代码拉取到本地git checkout maingit pull upstream main运行git log查看最近的提交验证最新提交就是 PR 的发布提交。发布提交的格式为chore(release): v11.2.0-rc.0如果不是该提交说明 PR 尚未合并等待合并后重新拉取。按q退出日志。给发布提交打上注释 tag并推送到upstreamgit tag -a v11.2.0-rc.0 -m v11.2.0-rc.0git push upstream v11.2.0-rc.0验证推送 tag 是否触发了Release Workflow的运行见 .github/workflows/release.yml。该工作流监听v*格式的 tag 推送事件!v10*被排除v10 有独立的 v10-release.yml。源码解读Version Workflow 如何生成版本号从 .github/workflows/version.yml#L50-L61 可以看到三种发布类型对应三条 Lerna 命令# preminor从当前稳定版生成下一个 minor 的 RC 版本如 v11.1.0 - v11.2.0-rc.0 yarn lerna version preminor --no-git-tag-version --preid rc --yes # prerelease在既有 RC 基础上递增如 v11.2.0-rc.0 - v11.2.0-rc.1 yarn lerna version prerelease --no-git-tag-version --preid rc --yes # minor正式升版如 v11.2.0-rc.0 - v11.2.0 yarn lerna version minor --no-git-tag-version --no-push --yes关键点在于--preid rc它把预发布标识符固定为rc使 Lerna 生成的版本形如v11.2.0-rc.0。同时--no-git-tag-version与--no-push表示本阶段只修改包版本号、不创建 tag 也不推送tag 由发布团队在 PR 合并后手动创建从而保证版本号变更与tag 标记两个动作解耦。仓库根目录的 lerna.json 配置了version: independent每个包独立版本号、npmClient: yarn以及提交信息模板chore(release): %s它还通过ignoreChanges排除了actions/**、**/docs/**、**/e2e/**、**/*.md等目录避免文档或测试改动误触发版本号变更。再次发布下一个 prerelease当一个 prerelease 发布后如果需要发布后续的候选版例如从v11.12.0-rc.0到v11.12.0-rc.1重复上述 Prelease 步骤但发布类型改为prerelease而不是preminor。Stable release 稳定发布流程稳定发布发生在最后一个周三并在当天稍晚完成。它必须发生在 prerelease 已经过测试和验证之后。流程如下手动触发Version Workflow指定minor作为发布类型提供本次发布的 tag。例如上一个版本是v11.1.0-rc.0则本次 tag 为v11.1.0。审查并批准工作流自动生成的 PR。等待 PR 被合并。合并后拉取上游最新代码git checkout maingit pull upstream main运行git log验证最新提交是发布提交格式如chore(release): v11.10.0按q退出。给发布提交打 tag 并推送git tag -a v11.2.0 -m v11.2.0git push upstream v11.2.0验证推送是否触发了Release Workflow的运行。Release Workflow 做了什么推送v*tag 后.github/workflows/release.yml 会被触发它做四件关键的事构建与质量门禁安装依赖、构建项目、构建 Storybook 并启动本地服务、运行 Playwright AVT无障碍自动化测试--grep avt、执行yarn ci-check等确保发布产物质量达标。以nextdist-tag 发布到 npm执行yarn lerna publish from-package --dist-tag next --no-verify-access --yes见 .github/workflows/release.yml#L68-L71。注意发布是落到next标签上而不是直接进latest。自动提升到latestpackages任务needs: build仅在 tag不包含-rc时执行if: contains(github.ref_name, -rc) false它调用仓库内置的 actions/promote 动作把所有已变更包的 npm dist-tag 从next提升为latest。这正是文档中自动将带新版本号的 Carbon 包提升到 latest的实现来源。创建 GitHub Release通过github.rest.repos.createRelease为当前 tag 创建 Release 记录并默认标记为 prerelease。Promote 动作的内部逻辑actions/promote/index.js 的实现细节值得展开它递归遍历所有 workspace跳过private字段为 true 的包存在一个 denylistcarbon-components与carbon/icons-vue不会被自动提升见 actions/promote/index.js#L14这与文档中手动 patch 发布时不要对 carbon-components 执行 dist-tag 提升的提醒完全对应对每个包它查询 npm registry 的dist-tags.latest若与当前版本不一致就执行npm dist-tag add nameversion latest支持DRY_RUN参数见 actions/promote/action.yml完成后在 Actions summary 中输出每个包的 Previous / Latest 对比表。发布后的收尾动作Release Workflow 成功后发布团队还需完成验证包已在 npm 上提升到latest例如检查carbon/react。用 Carbon CLI 生成 changelog 并更新最新 Release 的说明。在 monorepo 根目录执行./packages/cli/bin/carbon-cli.js changelog v11.5.0..v11.6.0changelog命令位于 packages/cli/src/commands/changelog.js它会先从 upstream 拉取最新 git 信息、获取 workspace 内所有包然后按range如v11.5.0..v11.6.0解析起止 tag为范围内每个包生成 changelog并询问是否复制到剪贴板可用-n/--noPrompt跳过交互。 3.在 GitHub Release 页面上取消勾选 this is a prerelease将发布正式标记为稳定版。 4.在 Slack 中发布发布公告渠道包括#carbon-announcements、#carbon-design-system、#carbon-react、#carbon-web-components。文档还提供了一份可直接复用的 Slack 公告模板Markdown 版与 Block Kit Builder 版核心结构为版本号链接 本次更新要点列表 引导用户查看 Release Radar 反馈渠道 致谢。更新 gatsby-theme-carbon 与 carbon-website稳定版 Release Workflow 完成后会自动触发deploy-packages工作流通过repository_dispatch的deploy-packages事件见 .github/workflows/release.yml#L102-L105对应的 .github/workflows/deploy-packages.yml 会分别在design-language-website与gatsby-theme-carbon两个仓库中自动升级 Carbon 依赖并打开 PR。后续操作审查、批准并合并gatsby-theme-carbon仓库中由该动作生成的 PR确认本次发布没有破坏性变更。如果上一轮发布的 PR 尚未合并已有 PR 会被自动更新。在gatsby-theme-carbon仓库运行release-it工作流触发gatsby-theme-carbon自身的发布。检查gatsby-theme-carbon是否已发布、其版本是否基于最新 Carbon。运行 Carbon 官网carbon-website仓库的 Update Carbon and gatsby-theme-carbon deps 工作流自动打开更新依赖的 PR。审查并批准该 PR。Post release发布后的支持与问题响应发布后需要更新 Release Radar 发布日历页面记录本次发布的实际情况。密切监控 Slack 渠道与 GitHub issues因为包从next切到latest后可能暴露此前未发现的破坏性变更。针对不同的问题类型文档给出了两条典型的处理策略Hotfix热修复如果问题自包含、可以快速解决走一次 patch 发布是最直接的解决方式Revert to previous stable release回滚到上一稳定版如果问题无法快速修复、或修复时间不可控回滚到上一个稳定版是更稳妥的选择。Manual Patch Release手动补丁发布当需要做一次计划外的off-cycle补丁发布、修复上一个版本中意外引入的缺陷时按以下步骤执行这也是理解 Lerna 手动版本控制的最佳实操案例进入本地 monorepo先同步最新状态git fetch upstream检出要打补丁的目标 tag通常是最新发布 taggit checkout vX.Y.Z基于该 tag 创建新分支分支名使用目标发布版本号即当前版本号递增0.0.1补丁位git checkout -b release/vX.Y.Z把希望纳入补丁的提交hotfixcherry-pick 进来git cherry-pick ######运行git log验证最新提交依次是tag 对应的发布提交 cherry-pick 进来的提交然后按q退出。用 Lerna 为自上次版本以来有变更的包统一升 patch 版本yarn lerna version patch --no-git-tag-version --no-push --yes检查变更文件确认所有受影响的包版本都只增加了0.0.1patch 位。运行yarn install更新依赖锁。确认此刻所有文件变更只涉及package.json和yarn.lock不应有其他文件被改动。提交并推送git add -Agit commit -m chore(release): vX.Y.Zgit push --set-upstream origin release/vX.Y.Z用该分支创建 PRbase分支设为main标题为chore(release): vX.Y.Z描述写明包含的 hotfix 提交。关闭这个 PR不合并并在关闭时注明这是手动发布该 PR 仅用于在 GitHub 历史中记录发布无需合并。给发布提交打 tag 并推送到 upstreamgit tag -a vX.Y.Z -m vX.Y.Zgit push upstream refs/tags/vX.Y.Z验证推送触发了 Release 工作流并成功且包以nexttag 发布到 npm。如果版本号正确手动把受影响的包提升到latest。注意不要对carbon-components包执行此操作与 actions/promote/index.js 中的 denylist 一致必须使用每个包各自生成的具体版本号而不是 GitHub 上的发布 tag建议以carbon-bot身份登录 npm CLI避免鉴权问题。对每个包执行将carbon-components-react替换为实际包名npm dist-tag add carbon-components-reactvX.Y.Z latest验证 npm 上包已提升到latest。在 monorepo 根目录用 Carbon CLI 生成 changelog 并更新 Release 说明./packages/cli/bin/carbon-cli.js changelog vA.B.C..vX.Y.Z值得一提的是仓库还提供了对应的自动化补丁工作流.github/workflows/version-patch.yml它接受tag、existing-tag以及最多 5 个待 cherry-pick 的提交 SHAcommit-1至commit-5自动完成检出既有 tag → 创建 release 分支 → cherry-pick →lerna version patch→ 提交 → 打 tag 并推送的全过程可以作为手动流程的参考实现。Previous releasesv10旧版本维护流程从 2022 年 3 月 v11 首发到2024 年 9 月 30 日Carbon 一直对上一个主版本v10提供维护支持。v10 在此期间只在被请求时接收缺陷修复以及关键安全更新。所有 v10 代码与资源已在 2024 年 9 月 30 日停止支持End of Support。文档明确注明以下 v10 发布流程相关内容仅出于留档posterity目的保留应在下一个主版本发布时从文档中移除。本仓库中对应的自动化工作流 .github/workflows/v10-version.yml 与 .github/workflows/v10-release.yml 至今仍保留供理解历史机制参考。如何判断 v10 是否需要发布打开仓库的 compare 页面在 base ref 下拉框的 tags 标签页中选择最近的v10.xtag在 compare ref 下拉框中选择v10分支查看 diff如果 diff 为空说明 v10 无需发布如果包含一串提交说明需要发布新的v10.x版本。同时检查以v10为 base 的 PR 队列——可能存在已打开、等待合并、可纳入本次发布的 PR。发布 v10 旧版本进入本地 monorepo检出 v10 分支并同步git checkout v10git pull upstream v10 --tags创建 release 分支git checkout -b release/vX.Y.Z安装依赖并确保工作区干净git status。运行 Lerna 为有变更的包升 patch 版本yarn lerna version patch \ --no-push \ --no-git-tag-version仔细核对版本增量作为 patch 发布不应包含破坏性变更如v10.14.0 → v11.0.0也不应包含 minor 变更如v10.59.1 → v10.60.0。确认无误后按y继续。快速校验运行yarn install --immutable确认所有版本已正确递增有时需要手动更新根目录package.json。运行yarn install提交并推送git add -Agit commit -m chore(release): vX.Y.Zgit push --set-upstream origin release/vX.Y.Z创建 PRbase分支设为v10标题chore(release): vX.Y.Z。 等待 PR 合并后拉取最新代码并验证最新提交是发布提交如chore(release): v10.59.1。打 tag 并推送git tag -a vX.Y.Z -m vX.Y.Zgit push upstream vX.Y.Z验证推送触发了 release 动作且包以v10-nexttag 发布到 npmv10 使用独立的 v10-release.yml其发布命令为yarn lerna publish from-package --dist-tag community --no-verify-access --yes发布到communitydist-tag。在 monorepo 根目录生成 changelog./packages/cli/bin/carbon-cli.js changelog vA.B.C..vX.Y.Z为单个包发布新 major某些情况下monorepo 中单个包需要 major 版本升级而不需要全仓库统一升 major。例如eslint-config-carbon需要新 major而其他包只升 patch且仓库 tag 保持在当前 majorv11.x不变。操作方式为手动版本控制切到main并git pull upstream main拉取最新创建版本分支如git checkout -b release/v11.23.1运行yarn lerna version --no-git-tag-version --no-push在交互式提示中为每个包选择合适的版本增量如果某个包不需要变更版本选择Custom Version并输入其现有版本号保持不变交互完成后运行yarn install更新yarn.lock提交chore(release): v11.23.1推送并打开 PR合并后从 等待 PR 被合并这一步开始走 Stable release 的后续流程打 tag 并触发自动化发布工作流。Troubleshooting常见故障排障指南Version 工作流成功但 PR 未创建查看工作流日志——很可能是Lerna 没有检测到需要发布的变更。这种情况常发生在自最近一个 tag 发布以来main分支没有新增内容。合并一个 PR 后重新运行工作流不要重跑上一次即可解决。Version 工作流失败如果 Version 工作流失败且无法定位原因只要你有仓库的 push 权限就可以在本地按工作流文件中的命令手动执行在干净的工作区拉取main最新代码并创建release/vX.Y.Z分支git checkout maingit pull upstream maingit checkout -b release/vX.Y.Zyarn installyarn build依次执行 version.yml 中的其余命令yarn build、yarn lerna ...、yarn install等。提交并推送到 PR此时你与Version 工作流成功处于同一进度git add .git commit -m chore(release): vX.Y.Zgit pushRelease 工作流失败同理只要有仓库 push 权限和 npm 发布权限可以在本地复现拉取对应 taggit checkout vX.Y.Z按 release.yml 中的命令顺序依次执行成功后手动为对应 tag 创建 GitHub Release并附上生成的 changelog。收到 unpkg 链接失效的报告这类问题通常是 unpkg 的默认行为导致的https://unpkg.com/carbon-components/*会解析为latesttag 对应的版本。如果latesttag 被误打到了v11.x版本上使用非版本化 unpkg 链接的用户就会解析到 v11 包——而 v11 包不再包含编译后的样式表从而出现样式丢失。修复方法是把latesttag 重新指回v10.xnpm dist-tag add carbon-components10.X.Y latest建议以carbon-bot身份登录 npm CLI 以避免鉴权问题。同时应引导用户养成给包名追加版本号前缀的习惯确保 unpkg 始终解析到最新的 v10 版本https://unpkg.com/carbon-components10/css/carbon-components.min.css https://unpkg.com/carbon-components10/scripts/carbon-components.min.js手动部署 v10 Storybook 时v11 的 Storybook 被发布到了 v7-react 站点原因是对应的部署工作流必须从v10分支运行手动触发时务必在分支下拉框中选择v10而不是默认分支否则产物会发布到错误的域名。结语一条贯穿自动化 人工把关的发布链路纵观整个发布流程Carbon 的发布体系呈现出清晰的自动化为主、人工把关为辅的设计Version Workflow 负责批量生成版本号与 release PRRelease Workflow 负责构建、测试、以next发布并自动提升到latestPromote 动作内置了包名 denylist 防止误提升deploy-packages通过repository_dispatch联动下游网站仓库而人工环节审查 PR、验证发布提交、打 tag、更新 changelog、发公告则构成了质量与合规的最后一道防线。理解这条链路无论是为 Carbon 贡献代码、维护自己的 monorepo 发布体系还是排查发布问题都能做到心中有数、按图索骥。【免费下载链接】carbonA design system built by IBM项目地址: https://gitcode.com/GitHub_Trending/carbo/carbon创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Carbon Design System 版本发布全流程解析：从 prerelease 到 stable 的时间驱动发布指南
Carbon Design System 版本发布全流程解析从 prerelease 到 stable 的时间驱动发布指南【免费下载链接】carbonA design system built by IBM项目地址: https://gitcode.com/GitHub_Trending/carbo/carbon本文以 IBM Carbon Design System 仓库monorepo中的 docs/release.md 为核心系统讲解其时间驱动的版本发布模型包括每两周一次的minor稳定版、提前数日发布的preminor/prerelease候选版以及按需发布的patch安全与缺陷修复版。你将掌握完整的手动发布操作序列Version Workflow → 打 tag → Release Workflow → npm dist-tag 提升、v10 旧版本维护流程、手动 patch 发布方法以及常见故障的排障手段同时本文结合仓库内 .github/workflows/version.yml、.github/workflows/release.yml、actions/promote/index.js、lerna.json 等源码与配置深入解释每个步骤背后的自动化原理。发布模型概述为什么是时间驱动Carbon Design System 采用**时间驱动time-based**而非攒够功能再发的发布模型规则非常简单每两周发布一个稳定的minor版本例如v11.2.0。完整的发布节奏记录在项目的 Release Radar 发布日历中。每次minor发布前几天先发布一个 prerelease预发布版。这个版本提供了一个集成窗口integration window让产品团队在稳定版正式发布前能够提前集成并验证这些改动。patch版本按需发布用于承载安全修复和缺陷修复不遵循固定排期。这一模型的核心价值在于既保证了发布节奏的可预期性每两周一次 minor又通过 prerelease 给下游产品留出充分的测试缓冲从而降低稳定版发布引入破坏性变更的风险。发布团队release lead 与 sidekick每一周的发布由**发布团队Release Team**协调完成团队由两名成员组成Release lead发布负责人负责管理发布本身包括测试Testing、发布Publishing、支持Support三大环节并在适当时候指导 sidekick 理解并跑通整个发布流程。Release sidekick发布搭档如果是第一次进入发布团队首要任务是学习如何运行发布流程同时协助 lead 完成测试、发布、支持等各项工作。两人配合共同保证发布流程的稳定执行也起到知识传递的作用。发布流程总览四个检查点一次完整的发布周期包含四个检查点检查点说明Prerelease预发布发布一个预发布版用于在稳定化之前测试发布候选Stable release稳定发布将 prerelease 提升为稳定版通过 npm 包对外可用Post release发布后为最新稳定版提供支持处理因提升到稳定版而产生的问题Previous release旧版本发布判断 v10 是否有新改动需要发布如有则发布v10 已于 2024-09-30 停止支持下面按检查点逐一展开实际操作步骤并标注每一步背后对应的自动化配置。Prerelease 预发布流程预发布发生在每个 sprint迭代的最后一个周一。此时发布团队需要执行以下操作手动触发 Version Workflow对应仓库中的 .github/workflows/version.yml让 Lerna 自动为所有包生成预发布版本号。该工作流通过workflow_dispatch暴露了两个必填输入见 .github/workflows/version.yml#L8-L23type发布类型可选值为minor、preminor、prerelease默认preminortag本次发布对应的 tag 名称例如v11.2.0-rc.0。指定preminor作为发布类型如果是发布下一个 prerelease则指定prerelease。提供本次发布的 tag。例如上一个版本是v11.1.0那么本次预发布的 tag 就是v11.2.0-rc.0可用仓库 tags 列表确认上一个版本的 tag。审查并批准该工作流自动生成的 Pull Request。该 PR 由peter-evans/create-pull-request动作创建分支名为release/tag提交信息与标题均为chore(release): tag见 .github/workflows/version.yml#L68-L82。等待 PR 被合并文档中明确用 强调此步骤不可跳过。合并后将上游最新代码拉取到本地git checkout maingit pull upstream main运行git log查看最近的提交验证最新提交就是 PR 的发布提交。发布提交的格式为chore(release): v11.2.0-rc.0如果不是该提交说明 PR 尚未合并等待合并后重新拉取。按q退出日志。给发布提交打上注释 tag并推送到upstreamgit tag -a v11.2.0-rc.0 -m v11.2.0-rc.0git push upstream v11.2.0-rc.0验证推送 tag 是否触发了Release Workflow的运行见 .github/workflows/release.yml。该工作流监听v*格式的 tag 推送事件!v10*被排除v10 有独立的 v10-release.yml。源码解读Version Workflow 如何生成版本号从 .github/workflows/version.yml#L50-L61 可以看到三种发布类型对应三条 Lerna 命令# preminor从当前稳定版生成下一个 minor 的 RC 版本如 v11.1.0 - v11.2.0-rc.0 yarn lerna version preminor --no-git-tag-version --preid rc --yes # prerelease在既有 RC 基础上递增如 v11.2.0-rc.0 - v11.2.0-rc.1 yarn lerna version prerelease --no-git-tag-version --preid rc --yes # minor正式升版如 v11.2.0-rc.0 - v11.2.0 yarn lerna version minor --no-git-tag-version --no-push --yes关键点在于--preid rc它把预发布标识符固定为rc使 Lerna 生成的版本形如v11.2.0-rc.0。同时--no-git-tag-version与--no-push表示本阶段只修改包版本号、不创建 tag 也不推送tag 由发布团队在 PR 合并后手动创建从而保证版本号变更与tag 标记两个动作解耦。仓库根目录的 lerna.json 配置了version: independent每个包独立版本号、npmClient: yarn以及提交信息模板chore(release): %s它还通过ignoreChanges排除了actions/**、**/docs/**、**/e2e/**、**/*.md等目录避免文档或测试改动误触发版本号变更。再次发布下一个 prerelease当一个 prerelease 发布后如果需要发布后续的候选版例如从v11.12.0-rc.0到v11.12.0-rc.1重复上述 Prelease 步骤但发布类型改为prerelease而不是preminor。Stable release 稳定发布流程稳定发布发生在最后一个周三并在当天稍晚完成。它必须发生在 prerelease 已经过测试和验证之后。流程如下手动触发Version Workflow指定minor作为发布类型提供本次发布的 tag。例如上一个版本是v11.1.0-rc.0则本次 tag 为v11.1.0。审查并批准工作流自动生成的 PR。等待 PR 被合并。合并后拉取上游最新代码git checkout maingit pull upstream main运行git log验证最新提交是发布提交格式如chore(release): v11.10.0按q退出。给发布提交打 tag 并推送git tag -a v11.2.0 -m v11.2.0git push upstream v11.2.0验证推送是否触发了Release Workflow的运行。Release Workflow 做了什么推送v*tag 后.github/workflows/release.yml 会被触发它做四件关键的事构建与质量门禁安装依赖、构建项目、构建 Storybook 并启动本地服务、运行 Playwright AVT无障碍自动化测试--grep avt、执行yarn ci-check等确保发布产物质量达标。以nextdist-tag 发布到 npm执行yarn lerna publish from-package --dist-tag next --no-verify-access --yes见 .github/workflows/release.yml#L68-L71。注意发布是落到next标签上而不是直接进latest。自动提升到latestpackages任务needs: build仅在 tag不包含-rc时执行if: contains(github.ref_name, -rc) false它调用仓库内置的 actions/promote 动作把所有已变更包的 npm dist-tag 从next提升为latest。这正是文档中自动将带新版本号的 Carbon 包提升到 latest的实现来源。创建 GitHub Release通过github.rest.repos.createRelease为当前 tag 创建 Release 记录并默认标记为 prerelease。Promote 动作的内部逻辑actions/promote/index.js 的实现细节值得展开它递归遍历所有 workspace跳过private字段为 true 的包存在一个 denylistcarbon-components与carbon/icons-vue不会被自动提升见 actions/promote/index.js#L14这与文档中手动 patch 发布时不要对 carbon-components 执行 dist-tag 提升的提醒完全对应对每个包它查询 npm registry 的dist-tags.latest若与当前版本不一致就执行npm dist-tag add nameversion latest支持DRY_RUN参数见 actions/promote/action.yml完成后在 Actions summary 中输出每个包的 Previous / Latest 对比表。发布后的收尾动作Release Workflow 成功后发布团队还需完成验证包已在 npm 上提升到latest例如检查carbon/react。用 Carbon CLI 生成 changelog 并更新最新 Release 的说明。在 monorepo 根目录执行./packages/cli/bin/carbon-cli.js changelog v11.5.0..v11.6.0changelog命令位于 packages/cli/src/commands/changelog.js它会先从 upstream 拉取最新 git 信息、获取 workspace 内所有包然后按range如v11.5.0..v11.6.0解析起止 tag为范围内每个包生成 changelog并询问是否复制到剪贴板可用-n/--noPrompt跳过交互。 3.在 GitHub Release 页面上取消勾选 this is a prerelease将发布正式标记为稳定版。 4.在 Slack 中发布发布公告渠道包括#carbon-announcements、#carbon-design-system、#carbon-react、#carbon-web-components。文档还提供了一份可直接复用的 Slack 公告模板Markdown 版与 Block Kit Builder 版核心结构为版本号链接 本次更新要点列表 引导用户查看 Release Radar 反馈渠道 致谢。更新 gatsby-theme-carbon 与 carbon-website稳定版 Release Workflow 完成后会自动触发deploy-packages工作流通过repository_dispatch的deploy-packages事件见 .github/workflows/release.yml#L102-L105对应的 .github/workflows/deploy-packages.yml 会分别在design-language-website与gatsby-theme-carbon两个仓库中自动升级 Carbon 依赖并打开 PR。后续操作审查、批准并合并gatsby-theme-carbon仓库中由该动作生成的 PR确认本次发布没有破坏性变更。如果上一轮发布的 PR 尚未合并已有 PR 会被自动更新。在gatsby-theme-carbon仓库运行release-it工作流触发gatsby-theme-carbon自身的发布。检查gatsby-theme-carbon是否已发布、其版本是否基于最新 Carbon。运行 Carbon 官网carbon-website仓库的 Update Carbon and gatsby-theme-carbon deps 工作流自动打开更新依赖的 PR。审查并批准该 PR。Post release发布后的支持与问题响应发布后需要更新 Release Radar 发布日历页面记录本次发布的实际情况。密切监控 Slack 渠道与 GitHub issues因为包从next切到latest后可能暴露此前未发现的破坏性变更。针对不同的问题类型文档给出了两条典型的处理策略Hotfix热修复如果问题自包含、可以快速解决走一次 patch 发布是最直接的解决方式Revert to previous stable release回滚到上一稳定版如果问题无法快速修复、或修复时间不可控回滚到上一个稳定版是更稳妥的选择。Manual Patch Release手动补丁发布当需要做一次计划外的off-cycle补丁发布、修复上一个版本中意外引入的缺陷时按以下步骤执行这也是理解 Lerna 手动版本控制的最佳实操案例进入本地 monorepo先同步最新状态git fetch upstream检出要打补丁的目标 tag通常是最新发布 taggit checkout vX.Y.Z基于该 tag 创建新分支分支名使用目标发布版本号即当前版本号递增0.0.1补丁位git checkout -b release/vX.Y.Z把希望纳入补丁的提交hotfixcherry-pick 进来git cherry-pick ######运行git log验证最新提交依次是tag 对应的发布提交 cherry-pick 进来的提交然后按q退出。用 Lerna 为自上次版本以来有变更的包统一升 patch 版本yarn lerna version patch --no-git-tag-version --no-push --yes检查变更文件确认所有受影响的包版本都只增加了0.0.1patch 位。运行yarn install更新依赖锁。确认此刻所有文件变更只涉及package.json和yarn.lock不应有其他文件被改动。提交并推送git add -Agit commit -m chore(release): vX.Y.Zgit push --set-upstream origin release/vX.Y.Z用该分支创建 PRbase分支设为main标题为chore(release): vX.Y.Z描述写明包含的 hotfix 提交。关闭这个 PR不合并并在关闭时注明这是手动发布该 PR 仅用于在 GitHub 历史中记录发布无需合并。给发布提交打 tag 并推送到 upstreamgit tag -a vX.Y.Z -m vX.Y.Zgit push upstream refs/tags/vX.Y.Z验证推送触发了 Release 工作流并成功且包以nexttag 发布到 npm。如果版本号正确手动把受影响的包提升到latest。注意不要对carbon-components包执行此操作与 actions/promote/index.js 中的 denylist 一致必须使用每个包各自生成的具体版本号而不是 GitHub 上的发布 tag建议以carbon-bot身份登录 npm CLI避免鉴权问题。对每个包执行将carbon-components-react替换为实际包名npm dist-tag add carbon-components-reactvX.Y.Z latest验证 npm 上包已提升到latest。在 monorepo 根目录用 Carbon CLI 生成 changelog 并更新 Release 说明./packages/cli/bin/carbon-cli.js changelog vA.B.C..vX.Y.Z值得一提的是仓库还提供了对应的自动化补丁工作流.github/workflows/version-patch.yml它接受tag、existing-tag以及最多 5 个待 cherry-pick 的提交 SHAcommit-1至commit-5自动完成检出既有 tag → 创建 release 分支 → cherry-pick →lerna version patch→ 提交 → 打 tag 并推送的全过程可以作为手动流程的参考实现。Previous releasesv10旧版本维护流程从 2022 年 3 月 v11 首发到2024 年 9 月 30 日Carbon 一直对上一个主版本v10提供维护支持。v10 在此期间只在被请求时接收缺陷修复以及关键安全更新。所有 v10 代码与资源已在 2024 年 9 月 30 日停止支持End of Support。文档明确注明以下 v10 发布流程相关内容仅出于留档posterity目的保留应在下一个主版本发布时从文档中移除。本仓库中对应的自动化工作流 .github/workflows/v10-version.yml 与 .github/workflows/v10-release.yml 至今仍保留供理解历史机制参考。如何判断 v10 是否需要发布打开仓库的 compare 页面在 base ref 下拉框的 tags 标签页中选择最近的v10.xtag在 compare ref 下拉框中选择v10分支查看 diff如果 diff 为空说明 v10 无需发布如果包含一串提交说明需要发布新的v10.x版本。同时检查以v10为 base 的 PR 队列——可能存在已打开、等待合并、可纳入本次发布的 PR。发布 v10 旧版本进入本地 monorepo检出 v10 分支并同步git checkout v10git pull upstream v10 --tags创建 release 分支git checkout -b release/vX.Y.Z安装依赖并确保工作区干净git status。运行 Lerna 为有变更的包升 patch 版本yarn lerna version patch \ --no-push \ --no-git-tag-version仔细核对版本增量作为 patch 发布不应包含破坏性变更如v10.14.0 → v11.0.0也不应包含 minor 变更如v10.59.1 → v10.60.0。确认无误后按y继续。快速校验运行yarn install --immutable确认所有版本已正确递增有时需要手动更新根目录package.json。运行yarn install提交并推送git add -Agit commit -m chore(release): vX.Y.Zgit push --set-upstream origin release/vX.Y.Z创建 PRbase分支设为v10标题chore(release): vX.Y.Z。 等待 PR 合并后拉取最新代码并验证最新提交是发布提交如chore(release): v10.59.1。打 tag 并推送git tag -a vX.Y.Z -m vX.Y.Zgit push upstream vX.Y.Z验证推送触发了 release 动作且包以v10-nexttag 发布到 npmv10 使用独立的 v10-release.yml其发布命令为yarn lerna publish from-package --dist-tag community --no-verify-access --yes发布到communitydist-tag。在 monorepo 根目录生成 changelog./packages/cli/bin/carbon-cli.js changelog vA.B.C..vX.Y.Z为单个包发布新 major某些情况下monorepo 中单个包需要 major 版本升级而不需要全仓库统一升 major。例如eslint-config-carbon需要新 major而其他包只升 patch且仓库 tag 保持在当前 majorv11.x不变。操作方式为手动版本控制切到main并git pull upstream main拉取最新创建版本分支如git checkout -b release/v11.23.1运行yarn lerna version --no-git-tag-version --no-push在交互式提示中为每个包选择合适的版本增量如果某个包不需要变更版本选择Custom Version并输入其现有版本号保持不变交互完成后运行yarn install更新yarn.lock提交chore(release): v11.23.1推送并打开 PR合并后从 等待 PR 被合并这一步开始走 Stable release 的后续流程打 tag 并触发自动化发布工作流。Troubleshooting常见故障排障指南Version 工作流成功但 PR 未创建查看工作流日志——很可能是Lerna 没有检测到需要发布的变更。这种情况常发生在自最近一个 tag 发布以来main分支没有新增内容。合并一个 PR 后重新运行工作流不要重跑上一次即可解决。Version 工作流失败如果 Version 工作流失败且无法定位原因只要你有仓库的 push 权限就可以在本地按工作流文件中的命令手动执行在干净的工作区拉取main最新代码并创建release/vX.Y.Z分支git checkout maingit pull upstream maingit checkout -b release/vX.Y.Zyarn installyarn build依次执行 version.yml 中的其余命令yarn build、yarn lerna ...、yarn install等。提交并推送到 PR此时你与Version 工作流成功处于同一进度git add .git commit -m chore(release): vX.Y.Zgit pushRelease 工作流失败同理只要有仓库 push 权限和 npm 发布权限可以在本地复现拉取对应 taggit checkout vX.Y.Z按 release.yml 中的命令顺序依次执行成功后手动为对应 tag 创建 GitHub Release并附上生成的 changelog。收到 unpkg 链接失效的报告这类问题通常是 unpkg 的默认行为导致的https://unpkg.com/carbon-components/*会解析为latesttag 对应的版本。如果latesttag 被误打到了v11.x版本上使用非版本化 unpkg 链接的用户就会解析到 v11 包——而 v11 包不再包含编译后的样式表从而出现样式丢失。修复方法是把latesttag 重新指回v10.xnpm dist-tag add carbon-components10.X.Y latest建议以carbon-bot身份登录 npm CLI 以避免鉴权问题。同时应引导用户养成给包名追加版本号前缀的习惯确保 unpkg 始终解析到最新的 v10 版本https://unpkg.com/carbon-components10/css/carbon-components.min.css https://unpkg.com/carbon-components10/scripts/carbon-components.min.js手动部署 v10 Storybook 时v11 的 Storybook 被发布到了 v7-react 站点原因是对应的部署工作流必须从v10分支运行手动触发时务必在分支下拉框中选择v10而不是默认分支否则产物会发布到错误的域名。结语一条贯穿自动化 人工把关的发布链路纵观整个发布流程Carbon 的发布体系呈现出清晰的自动化为主、人工把关为辅的设计Version Workflow 负责批量生成版本号与 release PRRelease Workflow 负责构建、测试、以next发布并自动提升到latestPromote 动作内置了包名 denylist 防止误提升deploy-packages通过repository_dispatch联动下游网站仓库而人工环节审查 PR、验证发布提交、打 tag、更新 changelog、发公告则构成了质量与合规的最后一道防线。理解这条链路无论是为 Carbon 贡献代码、维护自己的 monorepo 发布体系还是排查发布问题都能做到心中有数、按图索骥。【免费下载链接】carbonA design system built by IBM项目地址: https://gitcode.com/GitHub_Trending/carbo/carbon创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考