Gradle 使用指南

1. Gradle 支持范围

javachanges 可以在没有 Maven pom.xml 的 Gradle 仓库里做发布规划。

Gradle 路径支持：

• 通过 gradle.properties 加 settings.gradle、settings.gradle.kts、build.gradle 或 build.gradle.kts 识别仓库根目录
• 从 gradle.properties 读取当前版本
• 在 plan --apply true 时写回版本
• 从 Gradle include(...) 检测 package
• 用 root project name 支持单项目仓库
• changeset、status、changelog、release-plan manifest、GitHub release PR、GitLab release MR

preflight 和 publish 仍然是 Maven 发布辅助命令，会生成 Maven deploy 命令和 Maven settings.xml。Gradle artifact 的实际发布请继续使用 Gradle 原生 publishing task；javachanges 负责规划、changelog、manifest 和 release 自动化。

2. Gradle 仓库要求

Gradle 仓库应该把根版本放在 gradle.properties：

version=1.4.0-SNAPSHOT

javachanges 也接受这个兼容 key：

revision=1.4.0-SNAPSHOT

新 Gradle 仓库建议优先使用 version，因为这是标准 Gradle project property。

单项目 Gradle 仓库至少应具备：

gradle.properties
settings.gradle
build.gradle

或：

gradle.properties
settings.gradle.kts
build.gradle.kts

多项目 Gradle 仓库应在 settings.gradle 或 settings.gradle.kts 中声明 included projects。

Groovy DSL：

rootProject.name = 'payments'
include 'api', 'core'

Kotlin DSL：

rootProject.name = "payments"
include(":api", ":core")

支持嵌套 project path。include(":tools:cli") 在 changeset 中对应的 package key 是 cli。

3. 安装并运行 CLI

Gradle 仓库应使用正式发布的 CLI jar。Maven plugin 仍然适合 Maven 仓库，但 Gradle 构建应直接调用 CLI。

下载 jar：

mvn -q dependency:copy \
  -Dartifact=io.github.sonofmagic:javachanges:1.12.2 \
  -DoutputDirectory=.javachanges

设置一个复用变量：

export JAVACHANGES="java -jar .javachanges/javachanges-1.12.2.jar"

在 Gradle 仓库里执行：

$JAVACHANGES status --directory .

也可以生成 Gradle 原生 task 快捷入口：

$JAVACHANGES init-gradle-tasks --directory . --apply true --javachanges-version 1.12.2

首次设置时，也可以和其它起步文件一起生成：

$JAVACHANGES setup --directory . --apply-gradle-tasks true --javachanges-version 1.12.2

--apply true 会在 build.gradle.kts 中引用生成的 script plugin：

apply(from = "gradle/javachanges.gradle")

或在 build.gradle 中引用：

apply from: "gradle/javachanges.gradle"

如果想先手动审阅构建文件，可以省略 --apply true，再自行添加同一行。

之后常用命令可以直接通过 Gradle 执行：

./gradlew javachangesStatus
./gradlew javachangesAdd -Pjavachanges.summary="fix generated release notes" -Pjavachanges.release=patch
./gradlew javachangesPlan -Pjavachanges.apply=true
./gradlew javachangesGradlePublish -Pjavachanges.tag=v1.4.0

生成脚本还包含几个面向审阅和恢复路径的任务型别名：

./gradlew javachangesStatusJson
./gradlew javachangesApplyPlan
./gradlew javachangesRestorePlan

生成的脚本会从项目已有 repositories 解析 io.github.sonofmagic:javachanges，只有当项目没有配置任何 repository 时才会补 mavenCentral()。如果想改用已下载或本地构建的 CLI jar，可以传入：

./gradlew javachangesStatus -Pjavachanges.jar=.javachanges/javachanges-1.12.2.jar

Gradle tasks 默认把 --directory 指向 root project 目录。也可以覆盖目标目录或切换输出语言：

./gradlew javachangesStatus -Pjavachanges.directory=/path/to/repo -Pjavachanges.language=zh-CN

大多数已建模 property 也支持 command-scoped 覆盖。限定到命令的值只影响该 task，全局值仍作为其它 task 的默认值：

./gradlew javachangesStatus javachangesPlan -Pjavachanges.format=text -Pjavachanges.status.format=json

当 CLI 需要代理、编码或内存等 JVM 设置时，可以使用 javachanges.jvmArgs：

./gradlew javachangesStatus -Pjavachanges.jvmArgs="-Dfile.encoding=UTF-8 -Xmx512m"
./gradlew javachangesStatus -Pjavachanges.status.jvmArgs="-Dhttps.proxyHost=proxy.example.com -Dhttps.proxyPort=8080"

如果临时需要传入还没有专用 Gradle property 的 CLI 参数，可以用 javachanges.extraArgs 追加：

./gradlew javachangesStatus -Pjavachanges.extraArgs="--format json"

如果追加参数只应该作用于某一个命令，可以按 CLI command name 限定范围：

./gradlew javachangesStatus -Pjavachanges.status.extraArgs="--format json"
./gradlew javachangesGradlePublish -Pjavachanges.gradle-publish.extraArgs="--task publishAllPublicationsToMavenRepository"

如果你是在 javachanges 源码仓库中开发，可以这样指向一个 Gradle 仓库：

mvn -q -DskipTests compile exec:java -Dexec.args="status --directory /path/to/gradle-repo"

4. 单项目 Gradle 工作流

示例仓库：

my-library/
├── .changesets/
├── CHANGELOG.md
├── build.gradle.kts
├── gradle.properties
└── settings.gradle.kts

settings.gradle.kts：

rootProject.name = "my-library"

gradle.properties：

version=0.8.0-SNAPSHOT

创建 patch changeset：

$JAVACHANGES add --directory . \
  --summary "fix generated release notes" \
  --release patch

生成的 changeset 会使用 root project name：

---
"my-library": patch
---

fix generated release notes

查看并应用：

$JAVACHANGES status --directory .
$JAVACHANGES plan --directory .
$JAVACHANGES plan --directory . --apply true

应用后：

• gradle.properties 推进到下一个 snapshot 版本
• CHANGELOG.md 新增 release section
• 写入 .changesets/release-plan.json
• 写入 .changesets/release-plan.md
• 删除已消费的 .changesets/*.md

5. 多项目 Gradle 工作流

示例 settings.gradle.kts：

rootProject.name = "payments"
include(":api", ":core", ":tools:cli")

检测到的 package name：

Gradle project path	Changeset package key
:api	api
:core	core
:tools:cli	cli

创建一个影响两个 project 的 changeset：

$JAVACHANGES add --directory . \
  --summary "add payment retry metadata" \
  --release minor \
  --modules api,core

手写格式：

---
"api": minor
"core": minor
---

add payment retry metadata

如果变更影响所有检测到的 Gradle project，可以使用 --modules all：

$JAVACHANGES add --directory . \
  --summary "standardize Gradle publication metadata" \
  --release patch \
  --modules all

6. CI release-plan 自动化

在 GitHub Actions 或 GitLab CI 里，release planning 命令和 Maven 仓库一致：

java -jar .javachanges/javachanges-1.12.2.jar \
  github-release-plan \
  --directory "$GITHUB_WORKSPACE" \
  --github-repo "$GITHUB_REPOSITORY" \
  --execute true

GitLab：

java -jar .javachanges/javachanges-1.12.2.jar \
  gitlab-release-plan \
  --directory "$CI_PROJECT_DIR" \
  --project-id "$CI_PROJECT_ID" \
  --execute true

Gradle 仓库的 release-plan 自动化会 stage gradle.properties、CHANGELOG.md 和 .changesets/。

从已应用的 plan 创建 tag 时可以使用 fresh 元数据：

$JAVACHANGES github-tag-from-plan --directory . --fresh true --execute true
$JAVACHANGES gitlab-tag-from-plan --directory . --fresh true --execute true

7. 发布 Gradle artifacts

优先用 gradle-publish 作为 Gradle 原生发布任务的 dry-run 交接点：

$JAVACHANGES gradle-publish --directory . --tag v1.4.0

确认渲染出的 Gradle 命令后，再执行：

$JAVACHANGES gradle-publish --directory . --tag v1.4.0 --execute true

snapshot 发布同理：

$JAVACHANGES gradle-publish --directory . --snapshot true

如果只发布某个 Gradle project，传入检测到的 project name：

$JAVACHANGES gradle-publish --directory . --snapshot true --module api

这个命令会渲染 ./gradlew --no-daemon publish -Pversion=...；传入 --module api 时会渲染 ./gradlew --no-daemon :api:publish -Pversion=...。它不接管 Gradle 仓库凭据，凭据和 publication repository 仍然放在 Gradle build 或 CI 环境里。

如果你的 Gradle publication task 不是默认的 publish，传入 --task：

$JAVACHANGES gradle-publish --directory . --tag v1.4.0 --task publishAllPublicationsToMavenRepository

如果你的 Gradle build 已经从 gradle.properties 读取 version，应用 release plan 后该文件已经推进到下一个 snapshot。release tag 和 release notes 可以使用 fresh 元数据，真正发布逻辑仍放在 Gradle build 内部。

8. 常见错误

现象	原因	修复方式
Cannot find repository root	缺少 gradle.properties，或没有 Gradle settings/build 文件	添加 gradle.properties 和 settings.gradle(.kts) 或 build.gradle(.kts)
Cannot find version or revision	gradle.properties 没有支持的版本 key	添加 version=1.0.0-SNAPSHOT
Unknown module	changeset key 不匹配检测到的 project name	使用 include(...) 的最后一段，例如 :tools:cli 对应 cli
publish 命令渲染 Maven deploy	preflight 和 publish 是 Maven 专用辅助命令	Gradle artifact 发布使用 gradle-publish

9. 相关文档

需求	文档
第一次配置	快速开始
Maven 仓库流程	Maven 使用指南
命令细节	CLI 命令参考
可复制命令序列	命令实战手册
生成的 release manifest	Release Plan Manifest
CI release PR/MR 自动化	GitHub Actions 使用指南 和 GitLab CI/CD 使用指南