尧图网页设计 
Retrofit 版本发布完整指南从 VERSION_NAME 到 Maven Central 的自动化发布流程【免费下载链接】retrofitA type-safe HTTP client for Android and the JVM项目地址: https://gitcode.com/gh_mirrors/re/retrofit导读本文基于仓库根目录的 RELEASING.md 编写完整讲解 RetrofitA type-safe HTTP client for Android and the JVM从「准备发布」到「正式发布」再到「进入下一开发周期」的八个标准步骤。你将掌握如何更新版本号与 CHANGELOG、如何打 tag 并触发自动化发布、以及 GitHub Actions 工作流如何在 tag 推送后自动完成 Maven Central 发布、GitHub Release 创建和文档站点部署。文中所有结论均以仓库中的实际配置gradle.properties、CHANGELOG.md、.github/workflows/release.yaml为事实依据可直接照搬到任何基于 Gradle 的 JVM 库发布场景。一、发布流程总览一条从代码到中央仓库的流水线Retrofit 的发布流程在 RELEASING.md 中被精炼为 8 个顺序步骤核心思想是**「本地准备 远程触发」**阶段步骤操作对象目的发布准备1. 更新版本号gradle.properties 的VERSION_NAME把构建产物标记为正式版本发布准备2. 更新 CHANGELOGCHANGELOG.md记录本次发布内容发布准备3. 更新 READMEREADME.md 的 Download 小节让用户能看到新版本提交标记4. 提交git commit固化上述变更提交标记5. 打标签git tag标记发布点同时是 CI 的触发器进入下一周期6. 切回 SNAPSHOTgradle.properties为后续开发做准备进入下一周期7. 提交git commit固化开发版本触发发布8. 推送git push git push --tags触发自动化发布从第 8 步开始人工操作结束后续的 Maven Central 上传、GitHub Release 创建全部交给 .github/workflows/release.yaml 自动完成。下面逐一展开。二、发布前的仓库环境与版本约定在动手前先理解这个仓库的版本管理设计版本号唯一来源根目录 gradle.properties 中定义了VERSION_NAME当前仓库的状态为VERSION_NAME3.1.0-SNAPSHOT即处于 3.1.0 的**开发中快照Snapshot**阶段。同时该文件还定义了GROUPcom.squareup.retrofit2两者共同构成 Maven 坐标com.squareup.retrofit2:artifact:version。发布元信息gradle.properties 中还包含POM_URL、POM_SCM_URL、POM_LICENCE_NAME、POM_DEVELOPER_ID等字段以及mavenCentralPublishingtrue、mavenCentralAutomaticPublishingtrue、signAllPublicationstrue三个关键开关——它们表明发布插件会自动向 Maven Central 发布并签名所有产物签名密钥通过 CI 密钥注入见后文。版本节奏参考从 CHANGELOG.md 可见3.0.0 于 2025-05-15 发布其后紧跟 2.12.0且 3.x 与 2.x 保持向前二进制兼容当前Unreleased区块正积累 3.1.0 的新特性如Invocation.annotationUrl、RxJavaResult的 keep 规则等。发布者只需遵循约定正式版本号不带后缀如3.1.0开发版本号带-SNAPSHOT如3.1.1-SNAPSHOT。三、第 1 步更新 VERSION_NAME 为发布版本编辑根目录 gradle.propertiesGROUPcom.squareup.retrofit2 VERSION_NAME3.1.0这一行被 Gradle 构建脚本各模块的build.gradle文件读取作为所有模块retrofit、retrofit-adapters/*、retrofit-converters/*、retrofit-mock、retrofit-bom等 20 余个发布模块的统一版本号。由于多模块统一使用同一个属性不会出现子模块版本漂移。需要留意的配套改动目前 README.md 的 Download 小节写的还是上一发布版本com.squareup.retrofit2:retrofit:3.0.0与本步存在强关联见第 3 步。四、第 2 步更新 CHANGELOG.mdRELEASING.md 对 CHANGELOG 的要求包含三个子操作对照当前 CHANGELOG.md 的实际结构顶部是## [Unreleased]其下紧跟[Unreleased]: compare 链接形式的链接定义行再往下是按**New**/**Changed**/**Fixed**分类的条目可以清晰理解把Unreleased标题改为发布版本例如把## [Unreleased]改成## [3.1.0] - 2026-xx-xx日期格式参照已有的## [3.0.0] - 2025-05-15。为标题补充链接定义CHANGELOG 使用 Markdown 引用式链接因此必须把原来定义在[Unreleased]:后面的 URL 改指到新版本例如[3.1.0]: 该版本 tag 对应的比较地址否则标题里的版本号会变成无效链接。这正是 RELEASING.md 所说 Add a link URL to ensure the header link works 的含义。在顶部新增一个空的Unreleased区块用于记录接下来开发周期的新变更同时保留原[Unreleased]链接定义并指向新版本与 HEAD 的比较。除此之外正式发布时还应把**Fixed**下的占位文案 Nothing yet! 替换为实际修复内容这是仓库现有惯例。五、第 3 步同步 README.md 的 Download 小节更新 README.md 的 Download 小节使其反映新发布版本。当前内容为Download [the latest JAR][2] or grab from Maven central at the coordinates com.squareup.retrofit2:retrofit:3.0.0.发布 3.1.0 时其中的坐标应更新为com.squareup.retrofit2:retrofit:3.1.0。这一步骤确保用户从 README 复制到的依赖坐标始终指向可用的最新版本同时 README 中Snapshots of the development version are available in Sonatypessnapshotsrepository的描述与 CHANGELOG.md 中开发中快照发布到 Central Portal Snapshots 仓库的说明相互印证也解释了第 6 步切回 SNAPSHOT后的产物去向。六、第 4–5 步提交并打标签将上述三处变更统一提交然后打带注释的标签annotated tag$ git commit -am Prepare version X.Y.Z $ git tag -am Version X.Y.Z X.Y.Z两个命令的要点提交信息统一使用Prepare version X.Y.Z格式让版本准备提交在历史中一目了然使用-aannotate打带注释的标签而不是轻量标签标签信息Version X.Y.Z会被写入 Git 对象库为发布点保留作者、日期与说明等元数据标签名就是版本号本身如3.1.0这与后续 CI 触发条件见第八节直接对应。七、第 6–7 步切换到下一个 SNAPSHOT 版本并提交发布版本提交并打标后不要停留在已发布的版本号上继续开发而是立即在 gradle.properties 中把VERSION_NAME推进到下一个开发版本VERSION_NAME3.1.1-SNAPSHOT随后再次提交$ git commit -am Prepare next development version这样设计的好处是此后所有本地构建与快照发布都携带-SNAPSHOT后缀与已发布的正式版本在坐标层面彻底隔离避免开发构建意外覆盖正式版本的风险。从当前仓库VERSION_NAME3.1.0-SNAPSHOT的状态可以推断这正是上一次 3.0.0 发布后执行本步的结果——也就是说发布流程是一个首尾相接的闭环。八、第 8 步推送并触发自动化发布$ git push git push --tagsgit push把主分支本仓库为trunk的提交推送到远端git push --tags则把所有本地标签推送上去。推送 tag 是整条流水线的发令枪查看 .github/workflows/release.yaml 的触发条件即可确认on: push: tags: - **即任何 tag 的推送都会触发名为release的工作流。该工作流按顺序完成四件事1. 发布到 Maven Central- run: ./gradlew publish env: ORG_GRADLE_PROJECT_mavenCentralUsername: ${{ secrets.SONATYPE_CENTRAL_USERNAME }} ORG_GRADLE_PROJECT_mavenCentralPassword: ${{ secrets.SONATYPE_CENTRAL_PASSWORD }} ORG_GRADLE_PROJECT_signingInMemoryKey: ${{ secrets.GPG_SECRET_KEY }} ORG_GRADLE_PROJECT_signingInMemoryKeyPassword: ${{ secrets.GPG_SECRET_PASSPHRASE }}核心是执行./gradlew publish并通过环境变量注入四个机密secretsSonatype Central 的用户名/密码以及 GPG 私钥与其口令——后者用于代码签名与 gradle.properties 中signAllPublicationstrue相呼应。发布任务依托 gradle/libs.versions.toml 中声明的com.vanniktech:gradle-maven-publish-plugin版本 0.36.0完成多模块产物的坐标生成、签名与上传。2. 创建 GitHub Release- name: Extract release notes uses: ffurrer2/extract-release-notesv3 - name: Create release uses: ncipollo/release-actionv1 with: body: ${{ steps.release_notes.outputs.release_notes }} discussionCategory: Announcements发布说明直接从 CHANGELOG.md 中提取这正是第 2 步要求 CHANGELOG 格式严谨的原因并同步创建 Release 讨论帖。3. 构建发布版文档站点- run: | ./gradlew copyWebsiteDocs cd website npm install npm run build -- --mode release先由 Gradle 把最新 API 文档JavaDoc/Dokka拷入 website 目录再用 Astrowebsite/package.json以release模式构建站点。4. 部署站点- uses: JamesIves/github-pages-deploy-actionreleases/v3 with: branch: site folder: website/dist clean: true clean-exclude: | .nojekyll latest/**把构建产物部署到site分支latest/**被排除清理因为它保留的是快照版站点由 .github/workflows/build.yml 中 trunk 分支的publish任务部署两者互不覆盖。与日常构建工作流的边界值得区分的是tag 推送只触发release.yaml而日常的 PR、trunk 推送则触发 .github/workflows/build.yml。在 build.yml 中publish任务带有一个强约束if: github.repository square/retrofit github.ref refs/heads/trunk并且只有在该任务之前jvm、android、robovm、website四类检查含 Android API 21/24/26/29 的模拟器测试、RoboVM 测试等全部通过时快照版本才会发布到快照仓库。也就是说正式版发布看 tag快照发布看 trunk 主干 全量测试绿灯两条流水线互补共同支撑 CHANGELOG.md 中描述的开发中快照发布到 Central Portal Snapshots与正式版发布到 Maven Central 的双通道格局。九、发布流程自查清单按 RELEASING.md 的 8 步执行后可用以下清单快速复核是否遗漏gradle.properties 中VERSION_NAME是否为正式版本号无-SNAPSHOTCHANGELOG.md 顶部是否为## [X.Y.Z] - 日期且其链接定义已更新、新的Unreleased区块已就位README.md Download 小节的 Maven 坐标是否已更新为新版本已执行git commit -am Prepare version X.Y.Z已执行git tag -am Version X.Y.Z X.Y.Z务必使用-agradle.properties 是否已切回X.Y.Z1-SNAPSHOT已执行git commit -am Prepare next development version已执行git push git push --tags并确认 .github/workflows/release.yaml 被触发、./gradlew publish成功、Release 与文档站点均生成。结语Retrofit 的发布流程之所以精简到 8 步关键在于把决定发什么与怎么发彻底分离前 7 步由维护者在本地完成所有决策与录入版本号、CHANGELOG、README、tag第 8 步的推送则把剩余的一切——编译、签名、上传 Maven Central、生成 Release、部署文档——交给 tag 触发的工作流。对于任何同样使用 Gradle GitHub Actions Maven Central 的库项目这套版本准备提交 注释标签 CI 自动发布的组合拳都值得直接复用。【免费下载链接】retrofitA type-safe HTTP client for Android and the JVM项目地址: https://gitcode.com/gh_mirrors/re/retrofit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Retrofit 版本发布完整指南：从 VERSION_NAME 到 Maven Central 的自动化发布流程
Retrofit 版本发布完整指南从 VERSION_NAME 到 Maven Central 的自动化发布流程【免费下载链接】retrofitA type-safe HTTP client for Android and the JVM项目地址: https://gitcode.com/gh_mirrors/re/retrofit导读本文基于仓库根目录的 RELEASING.md 编写完整讲解 RetrofitA type-safe HTTP client for Android and the JVM从「准备发布」到「正式发布」再到「进入下一开发周期」的八个标准步骤。你将掌握如何更新版本号与 CHANGELOG、如何打 tag 并触发自动化发布、以及 GitHub Actions 工作流如何在 tag 推送后自动完成 Maven Central 发布、GitHub Release 创建和文档站点部署。文中所有结论均以仓库中的实际配置gradle.properties、CHANGELOG.md、.github/workflows/release.yaml为事实依据可直接照搬到任何基于 Gradle 的 JVM 库发布场景。一、发布流程总览一条从代码到中央仓库的流水线Retrofit 的发布流程在 RELEASING.md 中被精炼为 8 个顺序步骤核心思想是**「本地准备 远程触发」**阶段步骤操作对象目的发布准备1. 更新版本号gradle.properties 的VERSION_NAME把构建产物标记为正式版本发布准备2. 更新 CHANGELOGCHANGELOG.md记录本次发布内容发布准备3. 更新 READMEREADME.md 的 Download 小节让用户能看到新版本提交标记4. 提交git commit固化上述变更提交标记5. 打标签git tag标记发布点同时是 CI 的触发器进入下一周期6. 切回 SNAPSHOTgradle.properties为后续开发做准备进入下一周期7. 提交git commit固化开发版本触发发布8. 推送git push git push --tags触发自动化发布从第 8 步开始人工操作结束后续的 Maven Central 上传、GitHub Release 创建全部交给 .github/workflows/release.yaml 自动完成。下面逐一展开。二、发布前的仓库环境与版本约定在动手前先理解这个仓库的版本管理设计版本号唯一来源根目录 gradle.properties 中定义了VERSION_NAME当前仓库的状态为VERSION_NAME3.1.0-SNAPSHOT即处于 3.1.0 的**开发中快照Snapshot**阶段。同时该文件还定义了GROUPcom.squareup.retrofit2两者共同构成 Maven 坐标com.squareup.retrofit2:artifact:version。发布元信息gradle.properties 中还包含POM_URL、POM_SCM_URL、POM_LICENCE_NAME、POM_DEVELOPER_ID等字段以及mavenCentralPublishingtrue、mavenCentralAutomaticPublishingtrue、signAllPublicationstrue三个关键开关——它们表明发布插件会自动向 Maven Central 发布并签名所有产物签名密钥通过 CI 密钥注入见后文。版本节奏参考从 CHANGELOG.md 可见3.0.0 于 2025-05-15 发布其后紧跟 2.12.0且 3.x 与 2.x 保持向前二进制兼容当前Unreleased区块正积累 3.1.0 的新特性如Invocation.annotationUrl、RxJavaResult的 keep 规则等。发布者只需遵循约定正式版本号不带后缀如3.1.0开发版本号带-SNAPSHOT如3.1.1-SNAPSHOT。三、第 1 步更新 VERSION_NAME 为发布版本编辑根目录 gradle.propertiesGROUPcom.squareup.retrofit2 VERSION_NAME3.1.0这一行被 Gradle 构建脚本各模块的build.gradle文件读取作为所有模块retrofit、retrofit-adapters/*、retrofit-converters/*、retrofit-mock、retrofit-bom等 20 余个发布模块的统一版本号。由于多模块统一使用同一个属性不会出现子模块版本漂移。需要留意的配套改动目前 README.md 的 Download 小节写的还是上一发布版本com.squareup.retrofit2:retrofit:3.0.0与本步存在强关联见第 3 步。四、第 2 步更新 CHANGELOG.mdRELEASING.md 对 CHANGELOG 的要求包含三个子操作对照当前 CHANGELOG.md 的实际结构顶部是## [Unreleased]其下紧跟[Unreleased]: compare 链接形式的链接定义行再往下是按**New**/**Changed**/**Fixed**分类的条目可以清晰理解把Unreleased标题改为发布版本例如把## [Unreleased]改成## [3.1.0] - 2026-xx-xx日期格式参照已有的## [3.0.0] - 2025-05-15。为标题补充链接定义CHANGELOG 使用 Markdown 引用式链接因此必须把原来定义在[Unreleased]:后面的 URL 改指到新版本例如[3.1.0]: 该版本 tag 对应的比较地址否则标题里的版本号会变成无效链接。这正是 RELEASING.md 所说 Add a link URL to ensure the header link works 的含义。在顶部新增一个空的Unreleased区块用于记录接下来开发周期的新变更同时保留原[Unreleased]链接定义并指向新版本与 HEAD 的比较。除此之外正式发布时还应把**Fixed**下的占位文案 Nothing yet! 替换为实际修复内容这是仓库现有惯例。五、第 3 步同步 README.md 的 Download 小节更新 README.md 的 Download 小节使其反映新发布版本。当前内容为Download [the latest JAR][2] or grab from Maven central at the coordinates com.squareup.retrofit2:retrofit:3.0.0.发布 3.1.0 时其中的坐标应更新为com.squareup.retrofit2:retrofit:3.1.0。这一步骤确保用户从 README 复制到的依赖坐标始终指向可用的最新版本同时 README 中Snapshots of the development version are available in Sonatypessnapshotsrepository的描述与 CHANGELOG.md 中开发中快照发布到 Central Portal Snapshots 仓库的说明相互印证也解释了第 6 步切回 SNAPSHOT后的产物去向。六、第 4–5 步提交并打标签将上述三处变更统一提交然后打带注释的标签annotated tag$ git commit -am Prepare version X.Y.Z $ git tag -am Version X.Y.Z X.Y.Z两个命令的要点提交信息统一使用Prepare version X.Y.Z格式让版本准备提交在历史中一目了然使用-aannotate打带注释的标签而不是轻量标签标签信息Version X.Y.Z会被写入 Git 对象库为发布点保留作者、日期与说明等元数据标签名就是版本号本身如3.1.0这与后续 CI 触发条件见第八节直接对应。七、第 6–7 步切换到下一个 SNAPSHOT 版本并提交发布版本提交并打标后不要停留在已发布的版本号上继续开发而是立即在 gradle.properties 中把VERSION_NAME推进到下一个开发版本VERSION_NAME3.1.1-SNAPSHOT随后再次提交$ git commit -am Prepare next development version这样设计的好处是此后所有本地构建与快照发布都携带-SNAPSHOT后缀与已发布的正式版本在坐标层面彻底隔离避免开发构建意外覆盖正式版本的风险。从当前仓库VERSION_NAME3.1.0-SNAPSHOT的状态可以推断这正是上一次 3.0.0 发布后执行本步的结果——也就是说发布流程是一个首尾相接的闭环。八、第 8 步推送并触发自动化发布$ git push git push --tagsgit push把主分支本仓库为trunk的提交推送到远端git push --tags则把所有本地标签推送上去。推送 tag 是整条流水线的发令枪查看 .github/workflows/release.yaml 的触发条件即可确认on: push: tags: - **即任何 tag 的推送都会触发名为release的工作流。该工作流按顺序完成四件事1. 发布到 Maven Central- run: ./gradlew publish env: ORG_GRADLE_PROJECT_mavenCentralUsername: ${{ secrets.SONATYPE_CENTRAL_USERNAME }} ORG_GRADLE_PROJECT_mavenCentralPassword: ${{ secrets.SONATYPE_CENTRAL_PASSWORD }} ORG_GRADLE_PROJECT_signingInMemoryKey: ${{ secrets.GPG_SECRET_KEY }} ORG_GRADLE_PROJECT_signingInMemoryKeyPassword: ${{ secrets.GPG_SECRET_PASSPHRASE }}核心是执行./gradlew publish并通过环境变量注入四个机密secretsSonatype Central 的用户名/密码以及 GPG 私钥与其口令——后者用于代码签名与 gradle.properties 中signAllPublicationstrue相呼应。发布任务依托 gradle/libs.versions.toml 中声明的com.vanniktech:gradle-maven-publish-plugin版本 0.36.0完成多模块产物的坐标生成、签名与上传。2. 创建 GitHub Release- name: Extract release notes uses: ffurrer2/extract-release-notesv3 - name: Create release uses: ncipollo/release-actionv1 with: body: ${{ steps.release_notes.outputs.release_notes }} discussionCategory: Announcements发布说明直接从 CHANGELOG.md 中提取这正是第 2 步要求 CHANGELOG 格式严谨的原因并同步创建 Release 讨论帖。3. 构建发布版文档站点- run: | ./gradlew copyWebsiteDocs cd website npm install npm run build -- --mode release先由 Gradle 把最新 API 文档JavaDoc/Dokka拷入 website 目录再用 Astrowebsite/package.json以release模式构建站点。4. 部署站点- uses: JamesIves/github-pages-deploy-actionreleases/v3 with: branch: site folder: website/dist clean: true clean-exclude: | .nojekyll latest/**把构建产物部署到site分支latest/**被排除清理因为它保留的是快照版站点由 .github/workflows/build.yml 中 trunk 分支的publish任务部署两者互不覆盖。与日常构建工作流的边界值得区分的是tag 推送只触发release.yaml而日常的 PR、trunk 推送则触发 .github/workflows/build.yml。在 build.yml 中publish任务带有一个强约束if: github.repository square/retrofit github.ref refs/heads/trunk并且只有在该任务之前jvm、android、robovm、website四类检查含 Android API 21/24/26/29 的模拟器测试、RoboVM 测试等全部通过时快照版本才会发布到快照仓库。也就是说正式版发布看 tag快照发布看 trunk 主干 全量测试绿灯两条流水线互补共同支撑 CHANGELOG.md 中描述的开发中快照发布到 Central Portal Snapshots与正式版发布到 Maven Central 的双通道格局。九、发布流程自查清单按 RELEASING.md 的 8 步执行后可用以下清单快速复核是否遗漏gradle.properties 中VERSION_NAME是否为正式版本号无-SNAPSHOTCHANGELOG.md 顶部是否为## [X.Y.Z] - 日期且其链接定义已更新、新的Unreleased区块已就位README.md Download 小节的 Maven 坐标是否已更新为新版本已执行git commit -am Prepare version X.Y.Z已执行git tag -am Version X.Y.Z X.Y.Z务必使用-agradle.properties 是否已切回X.Y.Z1-SNAPSHOT已执行git commit -am Prepare next development version已执行git push git push --tags并确认 .github/workflows/release.yaml 被触发、./gradlew publish成功、Release 与文档站点均生成。结语Retrofit 的发布流程之所以精简到 8 步关键在于把决定发什么与怎么发彻底分离前 7 步由维护者在本地完成所有决策与录入版本号、CHANGELOG、README、tag第 8 步的推送则把剩余的一切——编译、签名、上传 Maven Central、生成 Release、部署文档——交给 tag 触发的工作流。对于任何同样使用 Gradle GitHub Actions Maven Central 的库项目这套版本准备提交 注释标签 CI 自动发布的组合拳都值得直接复用。【免费下载链接】retrofitA type-safe HTTP client for Android and the JVM项目地址: https://gitcode.com/gh_mirrors/re/retrofit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考