Dependency Upgrade Workflow

This skill performs a full Gradle dependency upgrade for the Armeria project step by step.

Background: Minimum Java Version Per Module

Armeria is a multi-module project with different minimum Java version requirements. Before upgrading a dependency, always verify that the new version supports the minimum Java version required by the modules that use it.

core

brave5

brave6

eureka

grpc

grpc-kotlin

graphql-protocol

jetty9

junit4

junit5

kafka

kotlin

logback

logback12

logback13

micrometer-context

oauth2

prometheus1

protobuf

reactor3

resteasy

retrofit2

rxjava2

rxjava3

sangria

scala*

spring:boot2-*

dropwizard2

thrift0.9

thrift0.17

tomcat8

tomcat9

xds

zookeeper3

saml

bucket4j

consul

nacos

athenz

graphql

jetty10

jetty11

kubernetes

logback14

thrift0.18

thrift0.22

tomcat10

ai:mcp

jetty12

resilience4j2

spring:boot3-*

spring:spring6

spring:boot4-*

spring:spring7

When in doubt, check

settings.gradle

java

java11

java17

Step 1: Run dependencyUpdates

./gradlew dependencyUpdates

The report is saved to

build/dependencyUpdates/report.txt

Step 2: Parse the Report

Read

build/dependencyUpdates/report.txt

If a version looks ambiguous (unexpected format, major version bump, unusual naming), verify on Maven Central before proceeding: https://central.sonatype.com/artifact/{groupId}/{artifactId}

Step 3: Check Skip Hints and Java Version Compatibility

Before upgrading any dependency, check

dependencies.toml

# Don't upgrade Caffeine to 3.x that requires Java 11.
caffeine = "2.9.3"

# Upgrade once https://github.com/ronmamo/reflections/issues/279 is fixed.
reflections = "0.9.11"

# Ensure that we use the same ZooKeeper version as what Curator depends on.
zookeeper = "3.9.3"

If such a comment exists and the reason still applies, skip the upgrade and do not remove the comment.

If no comment exists, proceed with the Java version compatibility check:

1. Find which modules use this dependency in

   dependencies.toml

2. Determine the minimum Java version required by those modules (see table above)
3. Check the new library version's minimum Java requirement (Maven Central / release notes)
4. If the library's required Java > module's minimum Java → skip the upgrade and add a comment above the version entry explaining why (e.g.

   # X.Y requires Java 11

   )
5. If compatible → proceed with the upgrade

Step 4: Update dependencies.toml

Edit the

[versions]

dependencies.toml

dependencies.toml

Step 5: Cross-check Updated Versions

After editing

dependencies.toml

git diff dependencies.toml

dependencyUpdates

1. No entry was accidentally skipped — compare the report's "The following dependencies have later milestone versions" list against your edits. If a dependency appears in the report but not in the diff, either upgrade it or document why it was skipped.
2. Versions match the report — confirm each new version in the diff matches the latest version from the report, not a typo or intermediate version.
3. Pinned-version comments were respected — verify you did not upgrade a dependency whose comment says to skip it, and that you did not remove or contradict an existing comment.
4. Linked-version constraints are satisfied — some dependencies must stay in sync with others (e.g. ZooKeeper with Curator, Protobuf with gRPC). Read the comments above those entries and verify the constraint still holds after the upgrade.

Step 6: Upgrade Gradle Wrapper

Check the latest stable Gradle release at https://gradle.org/releases/ and update

gradle/wrapper/gradle-wrapper.properties

distributionUrl=https\://services.gradle.org/distributions/gradle-X.Y.Z-all.zip

Step 7: Verify the Build

Run the full build including tests to catch both compilation errors and runtime regressions:

./gradlew build --no-daemon

If there are compilation errors, API breaking changes, or test failures caused by the upgrade, fix them before proceeding.

Step 8: Commit

Create a commit with the exact message format below. Follow it strictly — do not add extra sections, reorder bullets, or change the structure:

Update dependencies

- {library-name} {old-version} -> {new-version}
- {library-name} {old-version} -> {new-version}
- Build
   - {library-name} {old-version} -> {new-version}
   - {library-name} {old-version} -> {new-version}

Rules:

• Each production dependency (api/implementation scope) gets one bullet:

  - {name} {old} -> {new}

• The

  - Build

  bullet groups build-only dependencies (testImplementation, annotationProcessor, relocated libs, non-transitive deps); nest them as sub-bullets with 3-space indent
• Use the library's official name if one exists (e.g.

  gRPC-Java

  ,

  Jackson

  ,

  Netty

  ,

  Kotlin

  ,

  Reactor

  ,

  Logback

  ,

  Micrometer

  ); otherwise use the key name as-is from

  dependencies.toml

• Sort entries alphabetically (A → Z) within each section
• If no build-only deps were upgraded, omit the

  - Build

  section entirely
• If any dependencies were not upgraded (due to Java version constraints, pinned-version comments, or linked-version constraints), list them under a

  - Unupdated

  section with the reason. This helps reviewers know which upgrades were intentionally skipped.

Example:

Update dependencies

- gRPC-Java 1.63.0 -> 1.64.0
- Jackson 2.17.0 -> 2.18.0
- Build
   - checkstyle 10.14.0 -> 10.17.0
   - ErrorProne 2.27.0 -> 2.28.0
- Unupdated
   - Caffeine 2.9.3 -> 3.2.0 (requires Java 11)
   - ZooKeeper 3.9.3 (pinned to Curator's version)