ARTICLE DETAIL

资讯详情

深耕网站建设与运营推广的一线实战洞察。

NG-ZORRO 版本发布指南:基于 `stage-release` 的完整发版工作流

NG-ZORRO 版本发布指南:基于 `stage-release` 的完整发版工作流 UI组件前端【免费下载链接】ng-zorro-antdAngular UI Component Library based on Ant Design项目地址https://gitcode.com/gh_mirrors/ng/ng-zorro-antd点击查看免费下载本篇技术指南以 NG-ZORROng-zorro-antd仓库的官方发布技能文档 .agents/skills/version-release/SKILL.md 为主体结合scripts/release/release.ts等源码实现系统讲解该仓库从「准备发版分支」到「发布 npm 包、部署官网、发布 GitHub Release」的完整流程。读者读完可掌握如何用非交互式prepare模式准备本地发版文件、如何维护三份 changelog、如何为 API 与 Demo 打版本标签、如何走 Azure 发布与部署管线以及整套流程中的安全红线与 Agent 操作清单。适用范围与关键项目事实本指南只针对NG-ZORRO/ng-zorro-antd仓库的真实发版流程不是通用的 npm 发布清单。它覆盖以下环节准备发版分支与发版 PR、使用 agent 友好的stage-release prepare模式准备本地发版文件、维护根目录 changelog 与两份文档 changelog、通过 Azure 发布管线发布 npm 包、通过 Azure 部署文档站点以及 GitHub Release、博客与社交通告等发布后跟进。在动手之前必须先记住几个容易踩坑的「项目事实」根目录 package.json 的版本号是0.0.0-NOT-USED不要把它当作真实发版版本。库的真实版本号位于 components/package.json当前为22.1.0。Angular 版本号 token 位于 components/version/version.ts其中VERSION new Version(22.1.0)。发版辅助脚本是npm run stage-release实现在 scripts/release/release.ts根 package.json 中定义为stage-release: tsx scripts/release/release.ts。不带子命令运行npm run stage-release会进入原始的交互式人工流程逐阶段选择 Fetch upstream → Bump version → Update changelog → Build release → Push library release → Push site release。Agent 工作应使用非交互式 prepare 模式npm run stage-release -- prepare --version version --base branch。prepare 模式只准备本地发版文件不会构建、推送、发布或部署。发版 PR 通常需要更新三份 changelog 文件根目录 CHANGELOG.md、docs/changelog.en-US.md 与 docs/changelog.zh-CN.md。构建、库发布与站点部署通常由 Azure 管线完成官方 npm 发布默认不执行本地npm publish。动手前的仓库状态检查不要凭空猜测仓库状态先执行如下检查命令git status --short git branch --show-current git remote -v node -v cat components/package.json git tag --list | grep -v -E (experimental|alpha|resource) | sort -V | tail -20需要确认四件事工作树是干净的运行npm run stage-release之前必须如此。存在一个指向NG-ZORRO/ng-zorro-antd的 remote脚本会自动把它识别为 upstream。本地 Node 版本满足根 package.json 的engines要求当前为^22.22.3 || ^24.15.0 || 26.0.0。目标版本必须大于当前 components/package.json 中的版本。如果工作树里有用户未提交的改动除非用户明确要求否则不要覆盖或暂存这些改动。这一点在源码中也有体现scripts/release/release.ts 的prepareRelease会调用hasWorkingTreeChanges()内部执行git status --porcelain检查工作树若有未提交改动且非 dry-run 直接报错退出。使用非交互式 Prepare 模式准备发版 PR当用户要求「准备发版」「创建发版 PR」或「升级版本号」时统一使用 prepare 模式npm run stage-release -- prepare --version version --base branch示例npm run stage-release -- prepare --version 21.3.2 --base v21 npm run stage-release -- prepare --version 22.0.0 --base masterprepare 模式实际做了什么结合 scripts/release/release.ts 的实现prepare 模式会依次校验--version必填、格式合法validVersion在 scripts/release/parse-version.ts 中用正则/^(\d)\.(\d)\.(\d)(?:-(alpha|beta|rc)\.(\d))?$/校验校验工作树干净git status --porcelain通过getUpstreamRemoteName()自动探测指向NG-ZORRO/ng-zorro-antd的 remote 名执行git fetch --prune --tags remote base拉取目标基分支与标签用git merge-base --is-ancestor校验当前HEAD基于目标基分支校验目标版本大于当前版本checkVersionNumber在 parse-version.ts 中按 major → minor → patch → prerelease 依次比较prerelease 的优先级顺序为alpha beta rc从合并进基分支的标签中探测上一个发版标签git tag --merged base打印 changelog 边界previousTag..HEAD更新 components/package.json 与 components/version/version.tsupdateVersionFiles通过正则Version\(.\);替换版本号运行npm run changelog生成 changelog打印 changelog 边界与应使用的 PR 基分支。prepare 模式不会运行本地构建、推送发版分支、发布 npm 或部署站点。使用 --dry-run 先行演练想在不写任何文件的前提下核对基分支与 changelog 边界加--dry-runnpm run stage-release -- prepare --version 21.3.2 --base v21 --dry-rundry-run 模式下工作树有改动也只会告警而不会中断见 release.ts。原始的交互式模式仍保留给人类发版者npm run stage-release版本号规则prepare 模式只更新两处版本components/package.jsoncomponents/version/version.ts如果用户给了版本号且合法就使用它如果用户没给先查看当前版本、近期标签与待发布上下文再推荐一个版本。允许的格式为x.y.zx.y.z-alpha.nx.y.z-beta.nx.y.z-rc.n禁止手动编辑根 package.json 的发布版本那里是0.0.0-NOT-USED占位。Changelog三份文件的维护prepare 模式通过执行npm run changelog生成或刷新 changelog 内容。该命令在根 package.json 中定义为changelog: conventional-changelog -p conventionalcommits -i CHANGELOG.md -s --pkg components/package.json tsx scripts/site/replace-scope-prefix.ts即用conventional-changelogconventionalcommits 预设生成到 CHANGELOG.md再经scripts/site/replace-scope-prefix.ts处理 scope 前缀。生成结果只是起点还需要人工审阅并同步更新三份文件CHANGELOG.md保持根目录 changelog 既有格式## version (日期)的样式。docs/changelog.en-US.md保持文档页格式包括 frontmatterorder、title、toc、tag与 intro 内容。docs/changelog.zh-CN.md应为公开发布说明的中文翻译不能直接照抄英文原文。格式要点在每份文件顶部附近新增目标版本小节遵循该文件既有的## version与日期排版。不要把同一段 Markdown 无脑粘贴进三份文件——文档 changelog 有独立的页面结构。中文条目要自然翻译同时保留 PR 链接、issue 链接、commit 链接、组件 scope 与代码标识符。英文文案要适合作为公开发布说明。审阅每个发布条目时确认目标版本标题存在、重要 PR 已体现且分组合理、噪声已清理。英文与中文发布说明都审阅完成之前不要标记 changelog 步骤完成。API 与 Demo 的版本标签对于每个 minor 或 major 发版在 changelog 审阅之后、发版 commit 与 PR 之前这是必做步骤。需要为发布范围内新引入的特性在其既有 API 文档和 Demo 文档中补上缺失的版本标签。Patch 版本跳过此步骤除非用户明确要求修正版本标签。在components/component/doc/index.en-US.md与index.zh-CN.md中使用 API 表格的Version/版本列。列缺失时新增该列无关行留空保留既有版本值保持表格单元格对齐包括空的 global-config 单元格。新 API 标注引入版本例如22.1.0。如果只是既有 API 新增了能力要限定表述responsive object: 22.1.0/响应式对象22.1.0不要暗示整个 API 是新的。在components/component/demo/demo.md的 YAML frontmatter 中添加version: version针对新引入或新演示该特性的 demo。这是 demo 版本徽标保留既有顺序、标题、双语描述与 demo 源码。使用发布历史中的实际引入版本。保留更早的版本标签bugfix 与未变化的 API 或 demo 不新增特性版本标签。此步骤只限于版本列与 demo frontmatter保留描述、类型、默认值、示例与指南内容。额外解释、API 改写或新 demo 属于单独提出的文档变更。完成标准每个新特性的适用 API 行与 demo 都已检查中英文版本标签一致diff 中只包含预期标签与必要的表格格式调整。没有适用 API 行或 demo 的特性不需要新增文字。提交并创建发版 PR创建发版分支git checkout -b release/version只暂存属于该 PR 的发版文件通常包括CHANGELOG.mddocs/changelog.en-US.mddocs/changelog.zh-CN.mdcomponents/package.jsoncomponents/version/version.ts版本标签步骤中修改过的组件 API 与 demo Markdown 文件提交信息使用chore(release): release version将发版分支推送到用户的 fork 或配置的origin然后创建 PR。使用仓库的 PR 模板.github/PULL_REQUEST_TEMPLATE.md。PR 基分支必须与 prepare 时的--base一致。例如 prepare 用了--base v21PR 就要打到NG-ZORRO/ng-zorro-antd:v21而不是master。正常公共发布列车release train的 PR 目标通常是master维护版本只有在明确要求时才使用对应的维护分支。这也是源码中pushLibraryRelease的行为基础交互模式会创建release/version分支并以chore(release): release version提交见 release.ts。构建、发布与部署交给 AzureAgent 的默认流程不要本地执行Build release、Push library release、Push site release。本地脚本交互模式虽包含这些阶段但项目预期的工作流是 Azure 负责构建发布产物发布 npm 包部署文档网站如果用户要求做一次本地构建作为额外 sanity check可以在明确说明「这只是验证、不是官方发布/部署路径」的前提下运行npm run build。Azure 发布与站点部署仅在发版 PR 通过 CI、维护者准备发布时使用此流程。官方包的发布通过 Azure 完成打开 Azure 发布管线。进入对应 release。点击Publish发布 npm需要审批。点击Deploy更新网站。不要为官方 NG-ZORRO 包本地执行npm publish除非维护者明确覆盖正常 Azure 流程。网站更新优先使用 Azure 的Deploy操作网站也可能通过 cron 自动更新手动登录服务器只是内部兜底手段不是 Agent 默认动作。站点发布在源码中有对应实现scripts/release/release-site.ts 会把构建输出拷贝进ng-zorro.github.io目录、过滤掉.DS_Store、schematics、server、.idea、.vscode、.git等文件创建release/version分支并提交release: version后推送。发布后的跟进npm 发布与站点部署完成后合并发版 PR 到目标分支。在 GitHub Releases 页面创建 GitHub Release对应仓库的 releases 入口。major 与 minor 版本更新官方博客。major 与 minor 版本准备简短的社交通告附上官网与发布说明链接。Patch 版本通常不需要博客或社交通告除非用户要求。安全红线Safety Rules整套流程中必须遵守以下规则不要把npm publish作为默认发布路径。不要从脏工作树开始发版。不要覆盖用户改动。用户要求维护版本时不要猜测发版分支先检查分支有歧义就问清楚。不要未经明确确认就驱动交互式npm run stage-release流程进入 build 或 push 阶段。不要创建基分支与prepare --base不一致的发版 PR。除非维护者明确要求不要手动创建或推送标签。构建失败、CI 失败或 Azure 发布步骤失败后不要继续。这些规则在 release.ts 的实现中均有一一对应的硬校验版本格式与递增校验、工作树干净校验、upstream remote 探测、HEAD基于基分支校验等。Agent 发版检查清单作为 Agent 协助 NG-ZORRO 发版时的完整步骤检查 git 状态、remotes、Node 版本、当前包版本与近期标签。判断这是 patch、minor、prerelease 还是维护版本。运行npm run stage-release -- prepare --version version --base branch。核对components/package.json、components/version/version.ts、CHANGELOG.md、docs/changelog.en-US.md、docs/changelog.zh-CN.md。对 minor 与 major 发版完成上述 API 与 demo 版本标签审阅。在release/version分支上提交发版文件。使用.github/PULL_REQUEST_TEMPLATE.md创建发版 PR基分支与prepare --base相同。创建 PR 后即停止除非用户明确要求继续 Azure 发布。官方发布使用 Azure 的Publish与Deploy不要默认本地npm publish。完成 GitHub Release、博客与社交通告等发布后任务如适用。关键文件索引用途路径发布技能官方文档.agents/skills/version-release/SKILL.mdstage-release 脚本入口scripts/release/release.ts版本号解析与校验scripts/release/parse-version.ts站点发布实现scripts/release/release-site.ts库真实版本号components/package.jsonAngular 版本 tokencomponents/version/version.ts根目录脚本定义package.json根 changelogCHANGELOG.md英文文档 changelogdocs/changelog.en-US.md中文文档 changelogdocs/changelog.zh-CN.md赞分享UI组件前端【免费下载链接】ng-zorro-antdAngular UI Component Library based on Ant Design项目地址https://gitcode.com/gh_mirrors/ng/ng-zorro-antd点击查看免费下载相关推荐Easydict 发布维护指南基于 release-easydict Skill 的 macOS 版本发布工作流Easydict 发布维护指南基于 release easydict Skill 的 macOS 版本发布工作流 本文围绕 Easydict 仓库的发布与维护桌面应用AI 应用Bindu 周版本发布工作流基于 YYYY.W.D 日历版本的 Tag 与 Release 实践Bindu 周版本发布工作流基于 YYYY.W.D 日历版本的 Tag 与 Release 实践 本文以 Bindu 仓库中的 .agents/workfloCherry Studio 发版自动化基于 prepare-release Skill 的完整 Release 工作流实战指南Cherry Studio 发版自动化基于 prepare release Skill 的完整 Release 工作流实战指南 导读 本文以 CherryHQ人工智能大模型AI 应用交互助手本地部署上一篇如何永久保存微信聊天记录并生成年度报告WeChatMsg新手完整教程下一篇requests-html在房地产中的应用房源数据采集与市场分析创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表