Spotless 版本发布流程全指南：从 CHANGES 修订、changelogPush 到真实项目冒烟测试

开发工具代码质量格式化【免费下载链接】spotlessKeep your code spotless项目地址https://gitcode.com/gh_mirrors/sp/spotless点击查看免费下载导读本文围绕仓库根目录的 RELEASE_CHECKLIST.md发布检查清单展开完整梳理 Spotless 从修订变更日志到逐个发布 lib 与插件再到在 Apache Beam、JUNG 等真实项目上做冒烟测试的全过程。读完你将掌握changelogPush这一核心发布命令的底层行为版本号抬升、Freshmark 渲染、Git 标签与 GitHub Release 创建、lib 与插件必须分步发布的顺序约束以及 Gradle / Maven 两侧验证新版本可用性的标准操作。需要说明的是正如清单开头所注We now do this automatically in CI——Spotless 的发布如今主要由 CI 自动完成这份清单更多是发布流程的权威定义与人工兜底参考。本文既还原清单的每一项操作也结合仓库中的构建逻辑与 CI 脚本解释每个动作背后的自动化实现与安全护栏。一、发布前的准备修订三份 CHANGES.md发布的第一步不是跑构建而是修订变更日志。Spotless 采用多模块仓库结构因此有三份相互独立的 CHANGES 文件需要同步维护CHANGES.md对应spotless-lib与spotless-lib-extra两个核心库plugin-gradle/CHANGES.md对应 Gradle 插件plugin-maven/CHANGES.md对应 Maven 插件。1.1 面向对象的区分根目录的 CHANGES.md 开头就写明如果你是 Spotless 用户而非开发者应该看的是两份插件各自的 CHANGES.md根目录这份文档是给 Spotless 开发者看的记录的是底层库的演进。这与settings.gradle.kts中的模块划分一一对应——仓库包含lib无依赖的可复用库、lib-extra大量依赖的可复用库、plugin-gradle、plugin-maven四个发布单元见 settings.gradle.kts。1.2 Keep a Changelog 格式约定三份 CHANGES 文件都声明遵循 keepachangelog 格式lib 从1.27.0之后、Gradle 插件从3.27.0之后、Maven 插件从1.27.0之后开始遵守每个版本条目按### Added、### Changed、### Fixed分类记录并保留## [Unreleased]段用于积累下一个版本的改动。以最近的 CHANGES.md 为例4.10.4版本条目下既有Bump default Eclipse JDT formatter version from4.40to4.41这样的依赖升级说明也有shortenFullyQualifiedTypes、expandWildcardImports等具体步骤的修复描述。这些条目不是摆设——发布脚本会直接读取它们生成 GitHub Release 的正文见下文第三节。二、发布顺序先 lib再逐个发布插件清单给出的核心发布命令只有两条# 如果必要先发布 libspotless-lib 与 spotless-lib-extra ./gradlew :changelogPush # 然后逐个发布插件一次一个 ./gradlew :plugin-gradle:changelogPush ./gradlew :plugin-maven:changelogPush2.1 为什么必须一次只发布一个逐个发布不是建议而是强制的构建约束。在 build-logic/src/main/kotlin/spotless.changelog.gradle.kts 中rootProject 挂接了gradle.taskGraph.whenReady钩子如果一次构建里同时出现多个changelogPush任务例如:changelogPush与:plugin-gradle:changelogPush并行会直接抛出IllegalArgumentException提示 Run changelogPush one at a time因为每个 tag/commit 只能对应一次发布如果正在发布的是插件:plugin-gradle:changelogPush或:plugin-maven:changelogPush而 lib 的 CHANGES 里还有未发布的改动同样会报错提示先执行:changelogPush否则插件将错过 lib 的新特性除非显式传入-PignoreUnreleasedLibtrue承认可以暂时不带上这些改动。2.2 changelogPush 到底做了什么changelogPush由com.diffplug.spotless-changelog插件提供配置同样在 spotless.changelog.gradle.kts配置项取值含义changelogFileCHANGES.md每个项目使用自己的 CHANGES 文件setAppendDashSnapshotUnless_dashPreleasetrue非发布构建自动追加-SNAPSHOT后缀只有-Preleasetrue才发布正式版本branchrelease发布操作基于release分支进行tagPrefixlib/、gradle/、maven/按项目类型打不同前缀的 Git 标签commitMessagePublished $kind/{{version}}发布提交信息{{version}}会被实际版本号替换tagMessage{{changes}}标签注释直接使用本次 CHANGES 内容runAfterPushgh release create ... --notes-from-tagpush 成功后自动创建 GitHub Release也就是说一条./gradlew :changelogPush会串联完成抬升 CHANGES 中的版本号将[Unreleased]变成正式版本号并追加新的 Unreleased 段→ 用 Freshmark 重新渲染 README 中的版本号 → 提交并推送 → 打标签 → 创建 GitHub Release。其中版本号写回 README这一步在 build-logic/src/main/kotlin/spotless.spotless-freshmark.gradle.kts 中实现changelogBumpFreshmark依赖changelogBump把versionNext作为渲染属性写回所有*.md随后changelogBumpFreshmarkGitAdd执行git add *.md并作为changelogPush的前置依赖。2.3 发布前的双保险publicationConfirmed 与发布脚本清单只给出了changelogPush命令但仓库的构建逻辑对它加了更严格的守卫运行changelogPush前必须已通过bash .github/scripts/publish-release.sh {lib|plugin-gradle|plugin-maven}完成制品发布并确认中央仓库Maven Central已经收件否则构建会直接失败并提示Publish and confirm the artifacts before pushing release tags. Use bash .github/scripts/publish-release.sh {lib|plugin-gradle|plugin-maven}.这背后是两次构建的协作模式见 .github/scripts/publish-release.sh第一次构建负责发布制品按组件类型选择发布任务——lib发布:lib:publishToMavenCentral与:lib-extra:publishToMavenCentralplugin-gradle额外发布:plugin-gradle:publishPlugins需要GRADLE_KEY/GRADLE_SECRET环境变量plugin-maven只发布:plugin-maven:publishToMavenCentral。同时执行changelogInternalPushWillRun与changelogCheck并携带-Preleasetrue -PmavenCentralDeploymentValidationPUBLISHED——后者要求构建结束前等待中央仓库确认制品已 PUBLISHED第二次构建负责打 tag因为制品已经发布成功这次运行changelogPush时通过-x显式排除所有发布任务避免重复上传或把上传推迟到构建末尾并传入-PpublicationConfirmedtrue满足前述守卫。这一先确认制品、再动 git的顺序有专门的单元测试守护.github/scripts/test_publish_release.py用伪gradlew模拟 Gradle 调用断言发布失败退出码非 0时绝不更新 changelog、绝不创建 tag而发布成功时一定是先出现PUBLISHED校验的发布调用、后出现带-PpublicationConfirmedtrue的 changelogPush 调用。CI 的sanity-check任务会在每次构建前运行python3 .github/scripts/test_publish_release.py见 .github/workflows/ci.yml相当于把发布顺序变成了一道自动化门禁。三、CI 化的发布入口deploy 工作流既然现在在 CI 中自动完成人工发布入口被封装为 GitHub Actions 的workflow_dispatch手动工作流见 .github/workflows/deploy.yml通过下拉框选择要发布的目标lib、plugin-gradle、plugin-maven、all以及用于补救的lib-recover从已存在的lib/versiontag 重新上传制品作业运行在environment: maven-central环境中该环境只允许release分支只有维护者能推送触发从而隔离 Nexus、GPG、Gradle Portal 等发布密钥发布所需的密钥通过ORG_GRADLE_PROJECT_*环境变量注入mavenCentralUsername/mavenCentralPasswordNexus、signingInMemoryKey/signingInMemoryKeyId/signingInMemoryKeyPasswordGPG。其中签名子密钥 ID 使用0xB74EC7C6Gradle 要求 8 位十六进制子密钥 ID相关工作流在 .github/workflows/release-snapshot.yml 中也有同步配置all模式按顺序依次执行三次publish-release.sh先lib、再plugin-gradle、最后plugin-maven与清单规定的发布顺序完全一致。另外.github/workflows/release-snapshot.yml 提供了一条只发布-SNAPSHOT版本的路径它会先校验四个项目的版本号都以-SNAPSHOT结尾拒绝任何正式版本用于在不切发布的情况下演练发布凭据与签名密钥。四、发布后的冒烟测试在真实项目上验证最新版本清单的最后一项关键工作是拿最新发布的 Spotless 到两个真实的开源项目上跑一遍分别验证 Gradle 插件与 Maven 插件4.1 Gradle 侧Apache Beam在 Apache Beam版本v2.13.0上验证 Gradle 插件把 buildSrc/build.gradle 中的 Spotless 版本号升级为刚发布的最新版执行./gradlew spotlessApply -PdisableSpotlessChecktrue这里-PdisableSpotlessChecktrue是 Spotless 暴露的属性开关用于在应用格式化时跳过检查任务减少大规模项目上不必要的校验开销。Beam 这种体量的项目依赖关系复杂用它跑一遍spotlessApply能有效暴露插件在新版本中的兼容性问题。4.2 Maven 侧JUNG在 JUNG提交bf7e5b9上验证 Maven 插件把 pom.xml 中的 Spotless 版本号改为最新版执行mvn spotless:apply -U清单特别强调了-U参数的作用Maven Central 上的制品同步可能存在延迟-U强制 Maven 刷新远程仓库的元数据与依赖而不是命中上一次的缓存失败。如果没有-U一旦首次解析时制品还没同步完成后续构建会一直复用缓存中的失败结果。4.3 为什么挑这两个项目从仓库构建配置可以推断选型逻辑Beam 使用 Gradle 构建系统且体量大适合验证 Gradle 插件在复杂多模块工程下的稳定性JUNG 是经典的 Maven 多模块 Java 库适合验证 Maven 插件。两者恰好覆盖 Spotless 的两条主力插件链路是清单中Test latest spotless on这一项的标准冒烟环境。五、收尾回访已发布的 PR 与 Issue清单的最后一项是Comment on all released PRs / issues。发布完成后维护者需要在发布涉及的 PR / Issue 上留言说明该改动已随哪个版本发布。这一步虽然是纯人工动作但对社区协作很重要——它让贡献者能确认自己的改动进入了哪个版本、何时可以升级依赖。这与三份 CHANGES.md 中每个条目都附带对应 PR/Issue 链接如(#3115)的做法一脉相承从 changelog 条目可以反向定位到代码改动与讨论上下文评论环节则把这个闭环的最后一环补上。六、小结发布流程全景图将清单与仓库实现对照Spotless 的发布流程可以归纳为四个阶段修订变更日志同步维护 CHANGES.md、plugin-gradle/CHANGES.md、plugin-maven/CHANGES.md遵守 keepachangelog 格式确认制品发布通过 .github/scripts/publish-release.sh 发布 lib / 插件并等待 Maven Central 确认PUBLISHED打 tag 生成 Release逐个运行./gradlew :changelogPushlib 优先由 spotless.changelog.gradle.kts 完成版本抬升、Freshmark 渲染、commit、tag 与gh release create真实项目冒烟测试在 Apache BeamGradle与 JUNGMaven上 bump 版本并执行spotlessApply/spotless:apply -U最后回访相关 PR / Issue。如今这些步骤大部分已由 deploy.yml 等 CI 工作流自动执行清单本身则沉淀为发布流程的定义文档与人工兜底手册。理解它就理解了 Spotless 整个版本生命周期的运转方式。赞分享开发工具代码质量格式化【免费下载链接】spotlessKeep your code spotless项目地址https://gitcode.com/gh_mirrors/sp/spotless点击查看免费下载相关推荐OpenEvolve 集成测试指南从 CI 快速冒烟到真实 LLM 全流程验证OpenEvolve 集成测试指南从 CI 快速冒烟到真实 LLM 全流程验证 导读 本文围绕 OpenEvolveAlphaEvolve 的开源实现仓库人工智能大模型AI Agent代码智能体自主智能体Mastra 稳定版发布冒烟测试全流程指南从 npm 发布确认到最终签署验证Mastra 稳定版发布冒烟测试全流程指南从 npm 发布确认到最终签署验证 导读 本文讲解 Mastra 开源仓库中面向 稳定版stable/full r人工智能Agent 框架AI AgentRAG后端awesome-aws 项目发布检查清单实战指南从冒烟测试到 PyPI 上线的完整流程awesome aws 项目发布检查清单实战指南从冒烟测试到 PyPI 上线的完整流程 本文是 awesome aws 开源仓库一个精选 AWS 库、开源仓文档知识库上一篇GIMP Resynthesizer告别繁琐克隆让图像修复像魔法般简单下一篇6个月精通大厂技术面试算法与系统设计完整学习指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考