# Upgrade Deps

> Upgrade Deps is an Agent Skill for development published in the line/armeria repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Upgrade Gradle dependencies and Gradle wrapper version

- Skill name: `upgrade-deps`
- Category: [Development](https://www.openparable.com/skill/development/1)
- Source: https://github.com/line/armeria/blob/HEAD/.claude/skills/upgrade-deps/SKILL.md
- Repository: line/armeria (5,124 GitHub stars when collected)

## SKILL.md

# 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.

| Java Version | Modules |
|-------------|---------|
| **8**  | `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` |
| **11** | `athenz`, `graphql`, `jetty10`, `jetty11`, `kubernetes`, `logback14`, `thrift0.18`–`thrift0.22`, `tomcat10` |
| **17** | `ai:mcp`, `jetty12`, `resilience4j2`, `spring:boot3-*`, `spring:spring6`, `spring:boot4-*`, `spring:spring7` |

When in doubt, check `settings.gradle` for the `java`, `java11`, or `java17` flag on each subproject.

## Step 1: Run dependencyUpdates

```
./gradlew dependencyUpdates --no-parallel
```

The report is saved to `build/dependencyUpdates/report.txt`.

## Step 2: Parse the Report

Read `build/dependencyUpdates/report.txt` to identify all outdated dependencies.
For each dependency, note the current version and the available latest version.

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` for a comment directly above
its version entry. Many pinned versions have an explicit reason, for example:

```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]` section in `dependencies.toml` to update the version strings.
The file is located at the root of the repository: `dependencies.toml`.

## Step 5: Cross-check Updated Versions

After editing `dependencies.toml`, re-read the full diff (`git diff dependencies.toml`) and
cross-check every changed entry against the `dependencyUpdates` report:

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`:

```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)
```

---

Source: https://www.openparable.com/skill/development/upgrade-deps (OpenParable). Cite the canonical URL above.
