/devkit.java.upgrade-dependencies

allowed-tools: Read, Bash, Edit, Write, Grep, Glob
argument-hint: "[scope] [strategy] [version]"
description: Manages safe and incremental dependency upgrades for Java/Maven/Gradle projects with breaking change detection and migration guides. Use when upgrading project dependencies or migrating to new library versions.

Java Dependency Upgrade Strategy

Overview

Plan and execute safe, incremental upgrades of Java project dependencies with minimal risk, proper testing, and clear migration paths for breaking changes.

Manages safe and incremental dependency upgrades for Java/Maven/Gradle projects with breaking change detection and migration guides. Use when upgrading project dependencies or migrating to new library versions.

Usage

/devkit.java.upgrade-dependencies $ARGUMENTS

Arguments

$1 specifies the scope (optional - defaults to `all`):

• `all` - Analyze all dependencies
• `spring` - Focus on Spring Boot and Spring Framework dependencies
• `testing` - Focus on test dependencies (JUnit, Mockito, AssertJ, Testcontainers)
• `security` - Prioritize security vulnerabilities
• `direct` - Only direct dependencies (not transitive)
• `<groupId:artifactId>` - Specific dependency (e.g., `org.springframework.boot:spring-boot-starter-web`)

$2 specifies the strategy (optional - defaults to `analyze`):

• `analyze` - Analyze and report available updates with risk assessment
• `plan` - Create detailed upgrade plan with incremental steps
• `migrate` - Generate migration guide for major version upgrades
• `execute` - Execute planned upgrades (requires confirmation)
• `rollback` - Create rollback strategy and backup current state

$3 specifies target version for specific dependency upgrades (optional):

• Version number (e.g., `3.2.0`, `5.3.31`)
• `latest` - Latest stable release
• `latest-minor` - Latest minor version
• `latest-patch` - Latest patch version

Execution Instructions

**Agent Selection**: To execute this task, use the following agent with fallback:

• Primary: `java-security-expert`
• If not available: Use `developer-kit:java-security-expert` or fallback to `general-purpose` agent with

`spring-boot-crud-patterns` skill

Context

• Build system: !`ls -la | grep -E "(pom\.xml|build\.gradle|build\.gradle\.kts)"`
• Current dependencies: !

`if [ -f pom.xml ]; then mvn dependency:tree | head -30; elif [ -f build.gradle ]; then ./gradlew dependencies --configuration compileClasspath | head -30; fi`

• Outdated dependencies: !

`if [ -f pom.xml ]; then mvn versions:display-dependency-updates 2>/dev/null | grep -E "\\->" | head -20; elif [ -f build.gradle ]; then ./gradlew dependencyUpdates 2>/dev/null | grep -E "\\->" | head -20; fi`

Upgrade Analysis Process

1. Dependency Inventory

Analyze current state:

• List all dependencies (direct and transitive)
• Identify outdated dependencies
• Check for known security vulnerabilities
• Detect dependency conflicts

2. Risk Assessment

Categorize updates by risk level:

• **PATCH** (Low risk): Bug fixes, no breaking changes
• **MINOR** (Medium risk): New features, backward compatible
• **MAJOR** (High risk): Breaking changes, API modifications
• **SECURITY** (Critical): Security vulnerabilities requiring immediate action

3. Breaking Change Detection

For each major version update:

• Fetch release notes and changelogs
• Identify deprecated APIs
• Detect removed features
• Find renamed packages/classes
• Check compatibility with other dependencies

4. Framework-Specific Patterns

Spring Boot Upgrades

When upgrading Spring Boot:

• Check Spring Boot migration guide
• Update parent POM version
• Review breaking changes in Auto-configuration
• Update application.properties/yml if needed
• Verify starter dependencies compatibility
• Check for deprecated @Configuration patterns
• Test Actuator endpoint changes

JUnit 4 to JUnit 5

When upgrading JUnit:

• Replace `@Test` imports
• Convert `@Before/@After` to `@BeforeEach/@AfterEach`
• Update assertions (AssertJ recommended)
• Migrate test runners to `@ExtendWith`
• Replace `@RunWith(SpringRunner.class)` with `@ExtendWith(SpringExtension.class)`

Mockito Upgrades

When upgrading Mockito:

• Update import statements
• Replace deprecated methods
• Check ArgumentMatchers changes
• Verify BDDMockito compatibility
• Update MockitoJUnitRunner usage

5. Compatibility Matrix

Check peer dependencies:

• Spring Boot → Spring Framework version
• Spring Framework → Java version
• JUnit 5 → Mockito version
• Hibernate → Java Persistence API version
• Testcontainers → Docker Java version

Upgrade Strategies

Strategy 1: Patch Updates (Safe)

# Maven: Update all patch versions
mvn versions:use-latest-releases -DallowMajorUpdates=false -DallowMinorUpdates=false

# Gradle: Update patch versions
./gradlew useLatestVersions --update-dependency-locks

**Testing**: Smoke tests + unit tests **Risk**: Very low **Timeline**: Same day

Strategy 2: Minor Updates (Careful)

# Maven: Update minor versions
mvn versions:use-latest-releases -DallowMajorUpdates=false

# Gradle with version catalog
./gradlew versionCatalogUpdate --no-major

**Testing**: Full regression suite **Risk**: Low to medium **Timeline**: 1-2 days

Strategy 3: Major Updates (Planned)

Individual upgrade with migration:

1. Create feature branch 2. Update single dependency 3. Fix breaking changes 4. Run comprehensive tests 5. Code review 6. Merge after validation

**Testing**: Full test suite + manual QA **Risk**: Medium to high **Timeline**: 3-7 days per major dependency

Strategy 4: Spring Boot Upgrade (Strategic)

# Check Spring Boot compatibility
curl -s https://spring.io/projects/spring-boot | grep -A 5 "supported versions"

# Incremental upgrade path
# Example: 2.7.x → 3.0.x → 3.1.x → 3.2.x

**Testing**: Integration tests with Testcontainers **Risk**: High **Timeline**: 1-2 sprints

Maven Commands

Analysis

# Che