企业官网建设流程全解析

Retrofit 版本发布完整指南：从 VERSION_NAME 到 Maven Central 的自动化发布流程

【免费下载链接】retrofitA type-safe HTTP client for Android and the JVM项目地址: https://gitcode.com/gh_mirrors/re/retrofit

导读

本文基于仓库根目录的 RELEASING.md 编写，完整讲解 Retrofit（A 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 个顺序步骤，核心思想是**「本地准备 + 远程触发」**：

从第 8 步开始，人工操作结束，后续的 Maven Central 上传、GitHub Release 创建全部交给 .github/workflows/release.yaml 自动完成。下面逐一展开。

二、发布前的仓库环境与版本约定

在动手前，先理解这个仓库的版本管理设计：

• 版本号唯一来源：根目录 gradle.properties 中定义了VERSION_NAME，当前仓库的状态为VERSION_NAME=3.1.0-SNAPSHOT，即处于 3.1.0 的**开发中快照（Snapshot）**阶段。同时该文件还定义了GROUP=com.squareup.retrofit2，两者共同构成 Maven 坐标com.squareup.retrofit2:<artifact>:<version>。
• 发布元信息：gradle.properties 中还包含POM_URL、POM_SCM_URL、POM_LICENCE_NAME、POM_DEVELOPER_ID等字段，以及mavenCentralPublishing=true、mavenCentralAutomaticPublishing=true、signAllPublications=true三个关键开关——它们表明发布插件会自动向 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.properties：

GROUP=com.squareup.retrofit2 VERSION_NAME=3.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.md

RELEASING.md 对 CHANGELOG 的要求包含三个子操作，对照当前 CHANGELOG.md 的实际结构（顶部是## [Unreleased]，其下紧跟[Unreleased]: <compare 链接>形式的链接定义行，再往下是按**New**/**Changed**/**Fixed**分类的条目）可以清晰理解：

1. 把Unreleased标题改为发布版本：例如把## [Unreleased]改成## [3.1.0] - 2026-xx-xx，日期格式参照已有的## [3.0.0] - 2025-05-15。
2. 为标题补充链接定义：CHANGELOG 使用 Markdown 引用式链接，因此必须把原来定义在[Unreleased]:后面的 URL 改指到新版本，例如[3.1.0]: <该版本 tag 对应的比较地址>，否则标题里的版本号会变成无效链接。这正是 RELEASING.md 所说 "Add a link URL to ensure the header link works" 的含义。
3. 在顶部新增一个空的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 Sonatype'ssnapshotsrepository"的描述与 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格式，让版本准备提交在历史中一目了然；
• 使用-a（annotate）打带注释的标签而不是轻量标签，标签信息Version X.Y.Z会被写入 Git 对象库，为发布点保留作者、日期与说明等元数据；
• 标签名就是版本号本身（如3.1.0），这与后续 CI 触发条件（见第八节）直接对应。

七、第 6–7 步：切换到下一个 SNAPSHOT 版本并提交

发布版本提交并打标后，不要停留在已发布的版本号上继续开发，而是立即在 gradle.properties 中把VERSION_NAME推进到下一个开发版本：

VERSION_NAME=3.1.1-SNAPSHOT

随后再次提交：

$ git commit -am "Prepare next development version"

这样设计的好处是：此后所有本地构建与快照发布都携带-SNAPSHOT后缀，与已发布的正式版本在坐标层面彻底隔离，避免"开发构建意外覆盖正式版本"的风险。从当前仓库VERSION_NAME=3.1.0-SNAPSHOT的状态可以推断，这正是上一次 3.0.0 发布后执行本步的结果——也就是说，发布流程是一个首尾相接的闭环。

八、第 8 步：推送并触发自动化发布

$ git push && git push --tags

git 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，并通过环境变量注入四个机密（secrets）：Sonatype Central 的用户名/密码，以及 GPG 私钥与其口令——后者用于代码签名，与 gradle.properties 中signAllPublications=true相呼应。发布任务依托 gradle/libs.versions.toml 中声明的com.vanniktech:gradle-maven-publish-plugin（版本 0.36.0）完成多模块产物的坐标生成、签名与上传。

2. 创建 GitHub Release

- name: Extract release notes uses: ffurrer2/extract-release-notes@v3 - name: Create release uses: ncipollo/release-action@v1 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 目录，再用 Astro（website/package.json）以release模式构建站点。

4. 部署站点

- uses: JamesIves/github-pages-deploy-action@releases/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 步执行后，可用以下清单快速复核是否遗漏：

1. gradle.properties 中VERSION_NAME是否为正式版本号（无-SNAPSHOT）；
2. CHANGELOG.md 顶部是否为## [X.Y.Z] - <日期>，且其链接定义已更新、新的Unreleased区块已就位；
3. README.md Download 小节的 Maven 坐标是否已更新为新版本；
4. 已执行git commit -am "Prepare version X.Y.Z"；
5. 已执行git tag -am "Version X.Y.Z" X.Y.Z（务必使用-a）；
6. gradle.properties 是否已切回X.Y.Z+1-SNAPSHOT；
7. 已执行git commit -am "Prepare next development version"；
8. 已执行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