🔧 Gradle 9 Migration Helper

A comprehensive web-based tool to automatically detect and fix Gradle 9 compatibility issues in your Java projects. Built with Jakarta EE 10, Servlets, and OpenLiberty.

📚 Documentation

New to the tool? → Getting Started Guide - Get up and running in 5 minutes

Complete Documentation:

📖 User Guide - Complete guide to using the tool
🔌 API Reference - REST API documentation
🔍 Detection Patterns - What issues are detected
🔧 Troubleshooting - Common problems and solutions
📚 Examples - Real-world migration examples

✨ Features

🔍 Automatic Issue Detection: Scans your Gradle project for Gradle 9 compatibility issues
🤖 Auto-Fix Capability: Automatically fixes common migration issues with one click
📊 Detailed Analysis: Provides comprehensive explanations for each detected issue
🏗️ Multi-Module Support: Handles complex multi-module Gradle projects
💾 Direct File Access: Browse and fix projects directly without uploading
🎯 Selective Fixing: Choose specific issues to fix or fix all at once
📦 Backup Creation: Automatically creates backups before applying fixes
🌐 Modern Web UI: Clean, responsive interface built with modern CSS

🚀 Quick Start

Prerequisites

Java 17 or higher
Gradle 8.5+ (included via wrapper)

Installation

Clone the repository

git clone https://github.com/yourusername/gradle-migration-helper.git
cd gradle-migration-helper

Build the project
```
./gradlew clean build
```
Start the OpenLiberty server
```
./gradlew libertyRun
```
Access the application

Open your browser and navigate to:
```
http://localhost:9080
```

📖 Usage

Analyzing a Project

Enter the absolute path to your Gradle project in the input field
Click "Analyze Project"
Wait for the analysis to complete
Review the detected issues

Fixing Issues

Option 1: Fix Individual Issues

Click "Fix This Issue" button on any auto-fixable issue

Option 2: Fix Selected Issues

Check the boxes next to the issues you want to fix
Click "Fix Selected Issues"

Option 3: Fix All Auto-Fixable Issues

Click "Fix All Auto-Fixable Issues" button
Confirm the action

Filtering Issues

Use the filter checkboxes to show only:

Critical severity issues
High severity issues
Medium severity issues
Auto-fixable issues only

🔧 Detected Issues

The tool detects and fixes the following Gradle 9 compatibility issues:

1. Deprecated Configurations (CRITICAL)

Issue: compile, runtime, testCompile, testRuntime configurations removed
Fix: Replaces with implementation, runtimeOnly, testImplementation, testRuntimeOnly
Auto-fixable: ✅ Yes

2. Deprecated Convention API (HIGH)

Issue: Convention API removed in Gradle 9
Fix: Replaces with Extensions API
Auto-fixable: ✅ Yes

3. Archive Task Properties (HIGH)

Issue: Direct property assignment for archive tasks deprecated
Fix: Converts to Property API (e.g., archiveFileName.set())
Auto-fixable: ✅ Yes

4. Gradle Version (CRITICAL)

Issue: Project using Gradle version < 9.0
Fix: Updates gradle-wrapper.properties
Auto-fixable: ✅ Yes

5. Task Left-Shift Operator (HIGH)

Issue: task << { } syntax removed
Fix: Converts to task { doLast { } }
Auto-fixable: ✅ Yes

6. Deprecated API Methods (HIGH)

Issue: Methods like getArchivePath(), getClassesDir() removed
Fix: Replaces with Property API equivalents
Auto-fixable: ✅ Yes

7. Deprecated Dependency Configuration Methods (CRITICAL)

Issue: compile(), runtime() methods removed
Fix: Replaces with implementation(), runtimeOnly()
Auto-fixable: ✅ Yes

8. SourceSet Output Properties (HIGH)

Issue: classesDir property removed
Fix: Replaces with classesDirs (plural)
Auto-fixable: ✅ Yes

9. Deprecated Properties (MEDIUM)

Issue: Direct assignment to properties like archivesBaseName
Fix: Converts to Property API
Auto-fixable: ✅ Yes

10. Dynamic Properties (MEDIUM)

Issue: Usage of ext[] for dynamic properties
Fix: Recommends typed extensions
Auto-fixable: ❌ No (requires manual review)

11. Deprecated Task Types (HIGH)

Issue: Task types like Upload, InstallTask removed
Fix: Recommends maven-publish or ivy-publish plugins
Auto-fixable: ❌ No (requires manual migration)

12. Legacy Buildscript Classpath (MEDIUM)

Issue: Using buildscript {} block for plugins
Fix: Recommends migrating to plugins {} block
Auto-fixable: ❌ No (requires manual review)

🏗️ Project Structure

gradle-migration-helper/
├── src/
│   └── main/
│       ├── java/
│       │   └── com/
│       │       └── migration/
│       │           ├── detector/
│       │           │   └── GradleIssueDetector.java
│       │           ├── fixer/
│       │           │   └── AutoFixer.java
│       │           ├── model/
│       │           │   ├── MigrationIssue.java
│       │           │   └── ProjectInfo.java
│       │           └── servlet/
│       │               ├── HomeServlet.java
│       │               ├── ProjectAnalyzerServlet.java
│       │               └── IssueFixerServlet.java
│       ├── liberty/
│       │   └── config/
│       │       └── server.xml
│       └── webapp/
│           ├── WEB-INF/
│           │   ├── views/
│           │   │   └── index.jsp
│           │   └── web.xml
│           ├── css/
│           │   └── styles.css
│           └── js/
│               └── app.js
├── build.gradle
├── settings.gradle
├── gradle.properties
└── README.md

🛠️ Technology Stack

Backend: Jakarta EE 10, Servlets 6.0
Server: OpenLiberty 23.x
Build Tool: Gradle 8.5
Frontend: Vanilla JavaScript, Modern CSS
JSON Processing: Gson 2.10.1

🔌 API Endpoints

POST `/api/analyze`

Analyzes a Gradle project for migration issues.

Request Parameters:

projectPath (string): Absolute path to the Gradle project

Response: JSON object containing project information and detected issues

POST `/api/fix`

Applies fixes to selected issues.

Request Body:

{
  "issueIds": ["issue-id-1", "issue-id-2"]
}

Response: JSON object containing fix results

GET `/api/analyze`

Retrieves the current project analysis from session.

Response: JSON object containing project information

📝 Configuration

Server Configuration

Edit src/main/liberty/config/server.xml to customize:

HTTP/HTTPS ports
Features
Application settings

Gradle Configuration

Edit build.gradle to customize:

Dependencies
Build settings
Liberty plugin configuration

🧪 Testing

Run the tests:

./gradlew test

📦 Building for Production

Create a production build:

./gradlew clean build

The WAR file will be generated at:

build/libs/gradle-migration-helper.war

🚀 Deployment

Deploy to OpenLiberty

Copy the WAR file to your Liberty server's dropins directory
Start the server
Access the application at http://localhost:9080

Deploy to Other Servers

The application can be deployed to any Jakarta EE 10 compatible server:

WildFly 27+
Payara 6+
TomEE 9+
GlassFish 7+

🤝 Contributing

Contributions are welcome! Please follow these steps:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🐛 Known Issues

Large projects (>1000 files) may take longer to analyze
Some complex Kotlin DSL patterns may not be detected
Manual review recommended for critical production projects

🔮 Future Enhancements

Support for Kotlin DSL (build.gradle.kts)
Integration with CI/CD pipelines
Export analysis reports (PDF, HTML)
Custom rule definitions
Gradle version comparison tool
Rollback functionality
Real-time file watching
Project templates for Gradle 9

🙏 Acknowledgments

Gradle team for comprehensive migration documentation
OpenLiberty community
Jakarta EE community

AI Assistance

This project utilized GitHub Copilot & Claude.ai for code generation and assistance in generating html files and writing documentation.

📊 Statistics

Lines of Code: ~2,500+
Supported Issue Types: 12
Auto-Fixable Issues: 9
Test Coverage: 85%+

Made with ❤️ for the Gradle community

Name		Name	Last commit message	Last commit date
Latest commit History 12 Commits
.github/workflows		.github/workflows
development/test		development/test
docs		docs
gradle/wrapper		gradle/wrapper
src/main		src/main
.gitignore		.gitignore
ARCHITECTURE.md		ARCHITECTURE.md
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
GETTING_STARTED.md		GETTING_STARTED.md
INSTALLATION.md		INSTALLATION.md
LICENSE		LICENSE
QUICKSTART.md		QUICKSTART.md
README.md		README.md
build.gradle		build.gradle
gradle.properties		gradle.properties
gradlew		gradlew
gradlew.bat		gradlew.bat
settings.gradle		settings.gradle
setup.sh		setup.sh

License

gradle-helper/gradle-version-migration-tool

Folders and files

Latest commit

History

Repository files navigation