Upgrade Deps

Dependency Upgrade Workflow

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

Background: Minimum Java Version Per Module

Central Dogma 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.

The minimum Java version for each module is determined by two things:

1. The flag assigned in settings.gradle (java, java17, etc.)
2. The project-level defaults in gradle.properties (javaSourceCompatibility=11, javaTargetCompatibility=11)

Resolution order in gradle/scripts/lib/java.gradle (extractTargetJavaVersion()):

• If the module has a java17 (or similar) flag → that version wins
• Otherwise → falls back to gradle.properties values → Java 11

When in doubt, check settings.gradle for the java or java17 flag on each subproject, and gradle.properties for the default javaTargetCompatibility.

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:

# Don't update `json-path` version
json-path = "2.2.0"

# 3.0.0 requires java 17
json-unit = "2.38.0"

# Ensure that we use the same ZooKeeper version as what Curator depends on.
# See: https://github.com/apache/curator/blob/master/pom.xml
#      (Switch to the right tag to find out the right version.)
curator = "5.9.0"

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:

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, 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: line/centraldogma — distributed by TomeVault.