开发工具CI/CDDevOps【免费下载链接】release-pleasegenerate release PRs based on the conventionalcommits.org spec项目地址https://gitcode.com/gh_mirrors/re/release-please点击查看免费下载本篇技术指南围绕 release-please 仓库中的 docs/java-releases.md 展开深入讲解面向 Google Cloud Java 客户端库团队设计的java-yoshi/java-yoshi-mono-repo策略族如何通过versions.txt清单统一管理制品版本如何使用内联与块状注解驱动代码中的版本替换以及 Java BOM 与 Java LTS 两套特殊场景下的版本决策逻辑。读完本文你将掌握这些策略的配置入口、版本占位符的书写规范、deps:提交到 BOM 版本提升的映射规则以及 LTS 分支-sp.N/-lts.N版本演进与SNAPSHOT快照的完整机制。背景Yoshi 策略面向谁文档开宗明义当前实现的 Java 发布策略是专门为 Google Cloud 的 Java 客户端库团队Yoshi量身定制的并非通用 Maven 项目的开箱即用方案。这一点在 src/strategies/java-yoshi.ts 中得到印证JavaYoshi直接继承自通用 Java 策略基类Java其核心假设是仓库中存在versions.txt清单文件。因此若你的仓库是典型的单体 Maven 项目官方建议优先使用maven策略递归更新所有pom.xml见 docs/java.md只有当仓库组织方式与 Google Cloud Java 库一致多制品、单一versions.txt主清单时才选择 Yoshi 策略族。策略的注册入口分别在 src/factory.tsjava-yoshi、java-yoshi-mono-repo与 src/factories/versioning-strategy-factory.tsservice-pack。版本管理的主清单versions.txtYoshi 策略依赖一个名为versions.txt的清单文件来跟踪所有制品的版本。其行格式为module:released-version:current-version真实样例见 test/fixtures/strategies/java-yoshi/versions.txt# Format: # module:released-version:current-version google-cloud-trace:0.108.0-beta:0.108.1-beta-SNAPSHOT grpc-google-cloud-trace-v1:0.73.0:0.73.1-SNAPSHOT第一列是制品artifact名称如grpc-google-cloud-trace-v1第二列是released版本即该分支上最近一次正式发布的版本第三列是current版本即 HEAD 上当前的版本通常带-SNAPSHOT后缀。解析与写回逻辑VersionsManifestupdatersrc/updaters/java/versions-manifest.ts实现了三个关键静态方法parseVersions按^([\w\-_]):([^:]):([^:])逐行解析将每行第一列映射为Version取第二列updateSingleVersion写回时若新版本含SNAPSHOT仅更新current列module:released:current否则将两列都更新为同一正式版本module:version:versionneedsSnapshot若没有任何一行的current版本带-SNAPSHOT后缀则返回true触发快照发布。文件缺失时JavaYoshi.getVersionsContent会抛出MissingRequiredFileErrorsrc/strategies/java-yoshi.ts可见versions.txt是该策略的硬性前置条件。用注解标记需要替换版本的代码行有了主清单接下来要解决仓库中哪些位置需要被替换的问题。Yoshi 策略采用在代码行末尾追加特殊注解的方式声明版本占位由JavaUpdateupdatersrc/updaters/java/java-update.ts负责扫描与替换。内联注解Inline Annotation在希望被替换的 semver 版本所在行的行尾注释中追加{x-version-update:artifact-name:current} {x-version-update:artifact-name:released}current使用versions.txt中该制品的当前HEAD版本released使用该制品在当前分支上最近一次已发布的版本。对应正则INLINE_UPDATE_REGEX /{x-version-update:([\w\-_]):(current|released)}/匹配后用VERSION_REGEX\d\.\d\.\d(-\w(\.\d)?)?(-SNAPSHOT)?定位行内版本号并替换为新值src/updaters/java/java-update.ts。一个典型用法是把版本写进代码注释中并随时保持同步// 每次发布时release-please 会把 1.2.2 替换为最新版本 String version 1.2.2; // {x-version-update:google-cloud-trace:current}块状注解Block Annotation当需要替换的版本分散在多行或单行内容过长不便内联时可用成对标记圈定区域{x-version-update-start:artifact-name:current|released} ...需要替换版本的多行代码... {x-version-update-end}JavaUpdate.updateContent的状态机逻辑src/updaters/java/java-update.ts在读到BLOCK_START_REGEX后进入块内模式将块内每一行命中VERSION_REGEX的部分替换为指定制品的目标版本直到遇见BLOCK_END_REGEX才退出。实测用例可见 test/updaters/fixtures/java-auth-readme.md其中 README 使用[//]: #形式的 Markdown 注释包裹{x-version-update-start:...}/{x-version-update-end}标记来维护多组版本号。快照发布时的行为差异注意updateContent中的一个关键细节当isSnapshot为真时只处理标注为current的注解(!this.isSnapshot || match[2] current)。原因在于快照 PR 只把 HEAD 推向新的-SNAPSHOT版本不应触碰代表上次正式发布的released标记。Java BOM从依赖提交推断 BOM 版本提升文档中的 Java Bom 一节描述的是Bill of Materials物料清单制品——一类特殊的pom.xml项目它本身不含业务代码只声明一组互相兼容的依赖版本。在该策略下release-please 会逐个检查仓库中的deps:提交依赖更新提交并从依赖更新的语义化版本提升类型反推 BOM 制品自身的版本提升类型例如某个依赖发生 major 版本提升则 BOM 制品的版本也应随之进行对应的 major 提升。换句话说BOM 的版本号是其所辖依赖最大公约数的体现依赖整体发生破坏性升级时BOM 必须同步 breaking bump否则消费者按旧 BOM 锁定依赖会出现不兼容组合。这也是为什么 BOM 项目中CHANGELOG_SECTIONSsrc/strategies/java.ts专门为deps类型提交配置了 Dependencies 章节——依赖变化在 Java 版本决策中占据独立而重要的位置。Java LTSservice-pack 版本方案文档中的 Java LTS 是 Yoshi 策略族里最特殊的一类版本方案versioning strategy它不遵循常规的 semver 递增而是面向LTS长期支持分支设计。版本演进规则假设 LTS 分支是从主线的1.2.3切出则后续版本依次为1.2.3 ← LTS 分支从主线切出的基线 1.2.3-sp.1 ← 第一个 service pack 1.2.3-lts.2 ← 第二个LTS 后续发布即版本号主体1.2.3保持不变只递增-sp.N/-lts.N后缀序号。实现位于 src/versioning-strategies/service-pack.tsServicePackVersionUpdate.bump用SERVICE_PACK_PATTERN /sp\.(\d)/匹配预发布后缀若已存在sp.N则递增为sp.N1否则从sp.1起步src/versioning-strategies/service-pack.tsServicePackVersioningStrategy覆盖determineReleaseType对任何提交都返回该VersionUpdater从而将整个 LTS 分支的版本决策强制收敛到 service pack 模式。该策略在 src/factory.ts 中被预置为 LTS 分支的默认版本策略在配置中通过versioning: service-pack或对应 factory 入口启用src/factories/versioning-strategy-factory.ts。lts-snapshotsp 之后的 SNAPSHOT文档特别强调LTS 发布使用一种特殊的lts-snapshot bump。以1.2.3-sp.1为例其后的快照版本将是1.2.3-sp.2-SNAPSHOT即快照不是简单追加-SNAPSHOT而是先把 service pack 序号推进到下一个sp.1→sp.2再挂上-SNAPSHOT后缀。这与通用 Java 策略中JavaAddSnapshotsrc/versioning-strategies/java-add-snapshot.ts的行为一致先用一个fix: fake fix假提交驱动一次 patch 级别 bump再在结果上追加-SNAPSHOT后缀保留已有 preRelease 时拼接为preRelease-SNAPSHOT。因此1.2.3-sp.1经 fake commit 提升为1.2.3-sp.2最终得到1.2.3-sp.2-SNAPSHOT。策略族全景java-yoshi 与 java-yoshi-mono-repo 的差异虽然关联文档聚焦于版本管理机制了解策略族全景有助于正确选型。两个策略共享同一套注解/清单体系差异在于更新范围JavaYoshisrc/strategies/java-yoshi.ts更新versions.txt并递归查找目标路径下的pom.xml、build.gradle、dependencies.properties及extra-files中配置的文件全部套用JavaUpdateJavaYoshiMonoReposrc/strategies/java-yoshi-mono-repo.ts面向多制品 monorepo额外处理README.md、Version.java、librarian.yaml并在存在根changelog.json时按子目录拆分提交、生成机器可读的ChangelogJson条目依赖各目录的.repo-metadata.json中的distribution_name。两者都实现了零提交也强制触发 SNAPSHOT 发布的postProcessCommits当提交列表为空时注入一个fake类型假提交src/strategies/java-yoshi.ts确保合并正式发布后立即产生快照 PR。1.0.0 晋升promotion两个策略的updateVersionsMap都内置了晋升逻辑当检测到RELEASE AS: 1.0.0提交注记时isPromotionCommit见 src/strategies/java-yoshi.ts所有稳定制品名称不以-vN[-alpha|beta|rc]结尾判定见isStableArtifact直接设为1.0.0而带 alpha/beta 后缀的制品仍按常规策略 bump。这解释了 Google Java 库常见的GA 发布流程一条release-as: 1.0.0的提交即可把整套稳定制品晋升为 1.0.0。配置速查与实践要点在 release-please 配置中启用在release-please-config.json中为 Java 库仓库配置策略与版本方案{ packages: { .: { release-type: java-yoshi, extra-files: [ README.md, src/main/java/com/example/Version.java ] } }, plugins: [] }release-type可选java-yoshi单仓库或java-yoshi-mono-repo多制品 monorepoextra-files声明除自动发现的pom.xml/build.gradle/dependencies.properties之外、需要用JavaUpdate注解机制更新的文件LTS 分支场景将versioning设置为service-pack。落地清单checklist仓库根目录必须存在versions.txtmodule:released:current格式缺失会抛MissingRequiredFileError在每个需要同步版本的代码行/代码块上正确书写x-version-update内联或块状注解制品名须与versions.txt第一列完全一致需要随正式发布推进的版本标current需要保持上次已发布版本语义的标released合并正式发布 PR 后release-please 会自动创建携带autorelease: snapshot标签的 SNAPSHOT PR见 docs/java.md 中关于快照 PR 的说明将versions.txt与注解位置推进到下一个-SNAPSHOT版本BOM 仓库中依赖的 breaking change 会传导为 BOM 制品的 major bumpLTS 分支请使用service-pack版本方案并接受-sp.N/-lts.N演进规则。已知边界Yoshi 策略是 Google Cloud Java 库专用方案强依赖versions.txt与注解约定通用 Maven 单体项目请改用maven策略自动更新所有pom.xml的/project/version子模块缺省版本时回退更新/project/parent/version见 docs/java.md 与 src/updaters/java/pom-xml.tsreleased注解在快照 PR 中不会被更新isSnapshot时仅处理current请勿将需要随快照推进的版本标为released该策略族的设计与实现细节可继续阅读 src/updaters/java/versions-manifest.ts、src/updaters/java/java-update.ts 及对应测试 test/strategies/java-yoshi.ts 深入验证。赞分享开发工具CI/CDDevOps【免费下载链接】release-pleasegenerate release PRs based on the conventionalcommits.org spec项目地址https://gitcode.com/gh_mirrors/re/release-please点击查看免费下载相关推荐release-please Java 与 Maven 发布策略SNAPSHOT 版本机制、pom.xml 自动更新与版本注解实战指南release please Java 与 Maven 发布策略SNAPSHOT 版本机制、pom.xml 自动更新与版本注解实战指南 本指南围绕 relea开发工具CI/CDDevOpsrelease-please 版本回滚策略安全处理发布失败情况release please 版本回滚策略安全处理发布失败情况 在软件开发过程中发布失败是难以避免的情况。release please 作为基于 conve开发工具CI/CDDevOpsrelease-please Java 版本自动更新用 x-version-update 标记让 README 中的 Maven、Gradle、SBT 依赖版本永不过期release please Java 版本自动更新用 x version update 标记让 README 中的 Maven、Gradle、SBT 依赖版开发工具CI/CDDevOps上一篇BadgerDB终极指南高性能Go语言键值数据库的完整教程下一篇终极Arachni性能优化指南7个技巧让Web安全扫描速度提升300%创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
