Renovate 主版本（Major Release）发布全流程指南：从 next-major 分支到 npm deprecate

Renovate 主版本（Major Release）发布全流程指南：从 next-major 分支到 npm deprecate

【免费下载链接】renovateHome of the Renovate CLI: Cross-platform Dependency Automation by Mend.io项目地址: https://gitcode.com/GitHub_Trending/re/renovate

本指南面向 Renovate 的维护者与贡献者，完整讲解 Renovate 项目如何规划、准备、合并并发布一个 Major 版本（如 v42、v44 级的大版本升级）。你将掌握：触发大版本发布的判定标准、基于next-major临时分支的合并工作流、绕过分支保护的 Git 推送方式，以及发布后涉及文档、Schema Store、GitHub Action、GitLab CI 与 npm 弃用（deprecate）的一整套收尾动作。本文内容以 docs/development/major-release.md 为骨架，并结合仓库中的语义化发布（semantic-release）配置与 CI 工作流源码进行纵深印证。

为什么需要单独一份 Major Release 指南

Renovate 采用 semantic-release 驱动自动化发布，常规的feat、fix、perf提交会自动生成 patch/minor 版本并发布。但Major 版本（主版本）不同：它包含破坏性变更（breaking changes），涉及 Node.js 运行时要求的提升、默认配置的变更、旧版本的弃用等，影响面覆盖所有自托管用户、GitHub Action 用户与 Mend 托管平台。因此，Major 版本的发布不能完全交给自动化流水线“静默”完成，而是需要维护者按一套显式流程人工编排：先聚合破坏性变更、再经临时分支合流、最后一次性推送到main触发发布。

本指南对应的原始文档位于 docs/development/major-release.md，属于开发者文档（docs/development/readme.md）的一部分，与其姊妹篇 docs/development/bump-node-major.md（Node.js LTS 大版本升级）配套阅读效果更佳。

何时才会发布 Major 版本

原文档明确：Renovate 没有固定的 Major 版本发布计划表（schedule）。是否发布主版本，取决于以下四个触发条件的累积情况：

触发条件	说明
Node.js 运行时要求升级	需要提升 Renovate 运行所要求的 Node.jsminor 或 major版本时，会以 Major 版本承载（详见下文“与 Node.js LTS 升级的关系”一节）
破坏性变更“积压”	仓库中积累了一定数量的 breaking changes，需要集中在一个大版本中释放
需要更广的可见度	某些变更需要更大的曝光，例如对config:best-practices预设默认行为的调整
少数例外场景的组合	上述情况同时出现、彼此叠加时

值得注意的是，这些判定标准与 docs/development/bump-node-major.md 中“何时移除旧 LTS 支持”的规则相互呼应：当一个 Node.js LTS 上游停止维护、或 Renovate 需要只有更新 LTS 才具备的特性、或维护多版本成本过高时，就会通过一个 Major 版本将旧的 Node 版本要求移除——其标准动作是更新package.json > engines > node，并在 PR 上打breaking标签、在标题中写入feat!: require node v...。当前仓库 package.json 中的engines要求即为"node": "^24.11.0"，正是这一机制的直观体现。

发布前的准备：盘点范围与起草发布说明

在正式动手之前，维护者需要先做两件事：

1. 确定下一个版本包含什么：通过 GitHub 的 Milestones（里程碑）视图查看下一个版本规划中挂载的 issue 与 PR。
2. 盘点积压的破坏性变更：分别检查带有breaking标签的 open issue 清单与 open PR 清单，把需要纳入本次 Major 的变更全部识别出来。

提前起草 Release Notes

原文档强烈建议提前起草发布说明（draft release notes），并放在 GitHub Discussion 或 Issue 上进行草稿，好处是：

• 可以预览 GitHub Flavoured Markdown（GFM）的实际渲染效果，避免发布后再修正格式；
• 可以在发布当天直接复用，节省临场编写的时间；
• 便于维护者团队提前评审文案。

原文档以 v42 版本为例，指出其发布说明就是提前在 Discussion 上起草的。这一环节与仓库的自动化发布机制衔接紧密：semantic-release 会根据 conventional commits 自动生成“基础版”发布说明（见 .releaserc.json 中的@semantic-release/release-notes-generator插件），维护者在发布后需要把提前起草的说明prepend（前置拼接）到自动生成的说明之上，形成最终版本。

分支工作流：用next-major汇聚破坏性变更

Major 发布的核心难点在于：破坏性变更 PR 平时无法直接合并到main（会立即触发 minor/patch 之外的发布行为或破坏main的稳定性）。原文档给出的方案是：在发布前几天，创建一条临时的、不受保护的汇聚分支next-major，把所有破坏性变更 PR 逐一改基（rebase）并合并进去，最后整体推回main。

完整步骤（编号为原文档顺序）：

1. 创建临时分支next-major（基于main创建）。关键约束：它不能是受保护分支（包括next分支），因为后续需要频繁 rebase。
2. 从next-major向main创建一条PR。
3. 给这条 PR 打上ci:fulltest标签，以触发完整测试套件。
4. 登记要关闭的 issue：把本次发布要修复的 issue 标记到该 PR 侧栏的 “Development - Successfully merging this pull request may close these issues.” 中，由 PR 合并统一关闭。
5. 对每个计划中的破坏性变更 PR：先 rebase 并整理好 Git 提交历史。注意：不需要在 commit 里写Closes #...，因为关闭关系已在 PR 层面设置好了。
6. 将这些破坏性变更 PR 的基础分支（base branch）改为next-major。
7. 逐个 approve 并合并进next-major。
8. 把最容易引发冲突的合并（大范围代码改动、部分依赖升级）尽量放到最后——这是原文档特别标注的经验之谈，目的是把冲突集中到最后一次性解决，避免反复 rebase。
9. 必要时将next-majorrebase 到最新main并重新推送。
10. 等待 CI 通过。

ci:fulltest标签在 CI 中的实际作用

从源码看，ci:fulltest并非摆设，它在 .github/workflows/build.yml 中被多次用作 job 的if条件（如第 66、660、699 行附近）：只有 PR 带有ci:fulltest标签（且非 draft）时，完整测试任务才会运行。这解释了为何原文档要求给next-major的 PR 打上该标签——它直接决定合并前能否获得完整 CI 背书。

正式发布：绕过分支保护的 Git 推送

当main趋于平静（没有新的常规提交涌入）、next-major已同步最新main、CI 全部通过时，即可执行正式发布。原文档给出了 v42 发布时实际使用的命令序列：

git checkout main git pull # make sure we're using what's pushed # also, do not edit anything interactively at this point, as it will break the PR closing mechanism if the commits are different git rebase origin/next-major # NOTE THAT THIS DOES NOT REQUIRE A FORCE PUSH git push

要点解读：

• 这是**“绕过分支保护要求”的一次普通git push，而不是git push --force**。main通常配置了分支保护（不允许直接推送），因此该操作需要具备相应权限的人执行。
• 整个过程中不要做任何交互式编辑——如果推送到main的 commit 与 PR 上的 commit 不一致，会导致 PR 侧的 issue 关闭机制失效（GitHub 依据 commit 哈希与 PR 的关联关系关闭 issue）。
• 必须以独立 commit 逐个推送，因为 semantic-release 会根据每个 commit 生成各自的 CHANGELOG 条目；若把所有改动 squash 成一个 commit，CHANGELOG 将丢失细粒度记录。仓库 .releaserc.json 中配置的 conventionalcommits 提交类型分段（Features / Bug Fixes / Performance Improvements / Documentation 等）正是为这一逐条生成机制服务的。

[!IMPORTANT] 最终向main的git push需要Maintain 角色权限，Renovate 的全体维护者均具备该权限。

推送后发生了什么：语义化发布流水线

推送到main后，CI 中的releasejob（见 .github/workflows/build.yml）会被触发，其执行逻辑与本文所述流程高度吻合，可作为“自动发布后半程”的源码佐证：

1. Check for newer commits：job 启动时与执行前会各做一次远端 SHA 比对，一旦发现main上出现了更新 commit，立即取消本次发布运行——这正是原文档“等main安静下来”在流水线中的强制化实现。
2. semantic-release：运行pnpm semantic-release --dry-run "$DRY_RUN"（第 939–941 行附近），由 .releaserc.json 决定版本号。其中tagFormat为"${version}"（不带v前缀），branches同时管理main、next（prerelease）以及maint/x.y.z维护分支。
3. release:prepare / release:publish：.releaserc.json中的@semantic-release/exec插件在 prepare 阶段执行pnpm release:prepare --version=... --channel=... --sha=... --tries=3 --platform=linux/amd64,linux/arm64，publish 阶段执行pnpm release:publish ...。这两个脚本的实现在 tools/prepare-release.ts 与 tools/publish-release.ts 中：
   • prepare：更新包版本（pnpm version <version> --no-git-tag-version --allow-same-version）、执行pnpm build、生成文档、构建并打包 mkdocs 站点（tmp/mkdocs-site.tgz）、用bake构建多平台 Docker 镜像；
   • publish：用bake('push', ...)推送 Docker 镜像，并用 cosign 对ghcr.io/renovatebot/renovate与renovate/renovate的 slim/full 镜像做签名。
4. 发布资产：.releaserc.json的assets配置会把tmp/docs.tgz与tmp/mkdocs-site.tgz附加到 GitHub Release 上（tools/docs/index.ts 负责生成docs.tgz）。发布后的docs.tgz正是后文“更新 Schema Store”环节下载使用的构件。

发布说明与 Maintainer Announcement

Release 自动生成后，维护者需要：

1. 等待发布完成（等待 CI 的 release job 结束）；
2. 取出提前起草的发布说明，prepend 到 semantic-release 自动生成的说明之前；
3. 在 GitHub Discussions 中创建Maintainer Announcement（维护者公告）发布完整说明，并可像 v42 那样附加一些关于上一个主版本的补充评论，帮助用户理解大版本之间的差异。

发布后的收尾清单

Major 版本发布并非终点，原文档列出了发布后必须跟进的一系列事项：

1. 监控 Discussions：密切关注社区讨论，尽早发现发布后暴露的 bug 并安排修复。
2. 合并文档大版本升级 PR：批准并合并将文档站点升级到新 Renovate 版本的 PR（例如 docs 相关 PR 所对应的版本号同步工作）。
3. 更新 GitHub Action 到下一个 major：
   • 批准并合并由 Renovate 自己提出的 GitHub Action 大版本升级 PR（即renovatebot/github-action的新 major）；
   • 确保 Action 的新 major 版本在 marketplace 中显示为默认版本。
4. 更新 GitLab CI 配置到下一个 major：同步升级renovate-runner仓库中的 GitLab CI 配置。
5. 向 Schema Store 提交 JSON Schema 副本：
   • 前往上一个 major 的最后一个 tagged release，下载其中的docs.tgz；
   • 解压并复制出renovate-schema.json、renovate-inherited-schema.json、renovate-global-schema.json三个文件；
   • 按 Schema Store 的 PR 构建要求提交（如增加必要的配置以让 PR 构建通过）。这三个 schema 文件由仓库的create-json-schema脚本（package.json）在构建时生成，是用户 IDE 校验与renovate-config-validator的基础。
6. 关闭本次发布的 Milestone。
7. 标记上一个 major 版本为 deprecated（弃用）：等 Mend Developer Platform 已上线新 major 一段时间后，执行 npm 弃用命令：

% npm deprecate renovate@"<44.0.0" "Renovate versions older than the latest major version are unsupported"

原文档给出的示例是<44.0.0，即旧于最新主版本的所有版本统一标记为不受支持——这也反证了当前仓库正处于 v44 之后的主版本周期。该命令只影响 npm 上renovate包的安装提示，并不会破坏已安装用户的既有环境，是一种温和的版本引导手段。

与 Node.js LTS 升级的联动

Major 发布最常见的动因之一就是 Node.js 运行时要求的提升。结合 docs/development/bump-node-major.md 可以梳理出完整链路：

• 新增一个 Node LTS 版本作为支持版本，通常在“即将成为官方 LTS 前 1～2 周”通过 Renovate 的 minor 版本完成；
• 移除旧 LTS 支持则必须走 Major 发布：更新 package.json 的engines.node、同步更新本地开发文档（docs/development/local-development.md）与 GitHub Actions 工作流中的 node 版本，并将对应 PR 标记为breaking（打标签 + 标题加feat!:前缀）。

由于engines.node的变更直接影响所有自托管用户能否运行新版本，它天然具备“需要广而告之”的属性，因此在原文档的 Major 触发条件中被列为第一优先级。

维护者自查清单

将本文流程压缩为一份可执行清单，供发布负责人逐项核对：

• 通过 Milestones 与breaking标签盘点本次发布范围
• 提前在 Discussion/Issue 起草并评审 Release Notes
• 从main创建不受保护的next-major分支，并建 PR 指向main
• 给 PR 打ci:fulltest标签并登记待关闭 issue
• 将各破坏性变更 PR 改基到next-major并逐一合并（冲突风险高的放最后）
• 必要时 rebasenext-major到最新main，等待 CI 全绿
• 用 Maintain 角色执行git rebase origin/next-major+git push（非 force，不交互编辑）
• 等待 release job 完成，拼接提前起草的 Release Notes，发布 Maintainer Announcement
• 合并文档、GitHub Action、GitLab CI 的 next major 升级
• 从上一 major 的docs.tgz提取 3 个 JSON Schema 提交到 Schema Store
• 关闭 Milestone，待平台切换后执行npm deprecate

小结

Renovate 的 Major 发布流程可以概括为一句口诀：“临时分支汇聚、一次性推送、自动流水线发布、人工收尾扩散”。next-major临时分支解决了破坏性变更无法常规合入main的矛盾；ci:fulltest标签保证了合流前后的完整验证；semantic-release 流水线（.releaserc.json、.github/workflows/build.yml、tools/prepare-release.ts、tools/publish-release.ts）承接了版本号决策、Docker 镜像构建签名与文档构件打包；而文档同步、Action/CI 升级、Schema Store 提交与 npm deprecate 则确保新主版本在生态中的可见性与旧版本的平滑退场。对于维护大型开源 CLI 工具的团队而言，这份流程在“自动化程度”与“人工把关”之间给出的平衡，极具参考价值。

【免费下载链接】renovateHome of the Renovate CLI: Cross-platform Dependency Automation by Mend.io项目地址: https://gitcode.com/GitHub_Trending/re/renovate