Skip to content

GETTING_STARTED.md

Latest commit

 

History

History
334 lines (250 loc) · 7.9 KB

GETTING_STARTED.md

File metadata and controls

334 lines (250 loc) · 7.9 KB

🚀 Getting Started with Gradle 9 Migration Helper

Welcome! This guide will help you get started with the Gradle 9 Migration Helper in just a few minutes.

What is This Tool?

The Gradle 9 Migration Helper is a web-based application that:

  • 🔍 Scans your Gradle projects for Gradle 9 compatibility issues
  • 📊 Reports detailed information about each issue
  • 🤖 Automatically fixes most common migration problems
  • 💾 Creates backups before making any changes
  • 🏗️ Supports multi-module projects

Quick Start (3 Steps)

1️⃣ Start the Server

# Navigate to project directory
cd gradle-migration-helper

# Start the server
./gradlew libertyRun

Wait for: The server gradleMigrationServer is ready to run a smarter planet.

2️⃣ Open the Application

Open your browser and go to:

http://localhost:9080

3️⃣ Analyze Your Project

  1. Enter your project path (e.g., /Users/yourname/projects/my-gradle-app)
  2. Click "Analyze Project"
  3. Review the detected issues
  4. Click "Fix All Auto-Fixable Issues" or select specific issues

That's it! 🎉

Understanding the Interface

Project Information Section

Shows:

  • Project name and location
  • Current Gradle version
  • Whether it's a multi-module project
  • List of modules

Statistics Cards

  • Total Issues: All detected problems
  • Critical Issues: Must-fix items for Gradle 9
  • Auto-Fixable: Issues that can be fixed automatically

Issues List

Each issue shows:

  • Title: Brief description
  • Severity: CRITICAL, HIGH, MEDIUM, or LOW
  • Description: What the problem is
  • Explanation: Why it needs to be fixed
  • Current Code: The problematic code
  • Suggested Fix: How to fix it
  • File Location: Where the issue is located

Filtering Options

  • Filter by severity (Critical, High, Medium)
  • Show only auto-fixable issues
  • Combine filters for precise results

Common Use Cases

Use Case 1: Migrating a Single-Module Project

# Example project structure
my-app/
├── build.gradle
├── settings.gradle
└── src/

Steps:

  1. Enter path: /path/to/my-app
  2. Click "Analyze Project"
  3. Review issues (typically 5-15 issues)
  4. Click "Fix All Auto-Fixable Issues"
  5. Done! Your project is Gradle 9 ready

Use Case 2: Migrating a Multi-Module Project

# Example project structure
my-app/
├── build.gradle
├── settings.gradle
├── core/
│   └── build.gradle
├── web/
│   └── build.gradle
└── api/
    └── build.gradle

Steps:

  1. Enter root path: /path/to/my-app
  2. Click "Analyze Project"
  3. Tool detects all modules automatically
  4. Issues are grouped by module
  5. Fix all at once or module by module

Use Case 3: Selective Fixing

When to use: You want to review changes before applying them

Steps:

  1. Analyze your project
  2. Review each issue carefully
  3. Check the boxes next to issues you want to fix
  4. Click "Fix Selected Issues"
  5. Review the results
  6. Repeat for remaining issues

Understanding Issue Types

🔴 CRITICAL Issues

Must fix - Will cause build failures in Gradle 9

  • Deprecated configurations (compile, runtime)
  • Deprecated dependency methods
  • Old Gradle version

Action: Fix immediately

🟠 HIGH Issues

Should fix - May cause problems or warnings

  • Deprecated API usage
  • Archive task properties
  • Deprecated methods

Action: Fix before upgrading to Gradle 9

🟡 MEDIUM Issues

Nice to fix - Best practices and future-proofing

  • Dynamic properties
  • Legacy buildscript syntax
  • Deprecated properties

Action: Fix when convenient

🟢 LOW Issues

Optional - Recommendations and suggestions

  • Code style improvements
  • Alternative approaches

Action: Consider for new code

Safety Features

Automatic Backups

Every time you fix an issue, the tool:

  1. Creates a timestamped backup (e.g., build.gradle.backup.1234567890)
  2. Applies the fix
  3. Reports the backup location

Restore from Backup

If something goes wrong:

# Find your backup
ls -la *.backup.*

# Restore it
cp build.gradle.backup.1234567890 build.gradle

Manual Review

Before fixing:

  1. Review the "Current Code" vs "Suggested Fix"
  2. Read the detailed explanation
  3. Understand the impact
  4. Then apply the fix

Tips and Best Practices

✅ Do's

  • ✅ Analyze before fixing
  • ✅ Read issue explanations
  • ✅ Test after fixing
  • ✅ Commit changes to version control
  • ✅ Fix critical issues first
  • ✅ Review backups location

❌ Don'ts

  • ❌ Don't skip reading explanations
  • ❌ Don't fix without backups
  • ❌ Don't ignore critical issues
  • ❌ Don't forget to test after fixing
  • ❌ Don't delete backup files immediately

Testing Your Fixed Project

After applying fixes:

# Navigate to your project
cd /path/to/your/project

# Clean build
./gradlew clean

# Build project
./gradlew build

# Run tests
./gradlew test

# If successful, you're ready for Gradle 9!

Keyboard Shortcuts

  • Enter in project path field: Start analysis
  • Ctrl/Cmd + Click on checkbox: Select multiple issues
  • Esc: Close dialogs

Troubleshooting

"No issues found"

✅ Great! Your project is already Gradle 9 compatible

"Error analyzing project"

  • Check the project path is correct
  • Ensure you have read permissions
  • Verify it's a valid Gradle project (has build.gradle)

"Fix failed"

  • Check file permissions
  • Ensure files aren't locked by another process
  • Review the error message
  • Try fixing manually using the suggested fix

Server won't start

  • Check if port 9080 is available
  • Verify Java 17+ is installed
  • Review server logs in build/wlp/usr/servers/*/logs/

Next Steps

After Your First Analysis

  1. ✅ Review all detected issues
  2. ✅ Fix auto-fixable issues
  3. ✅ Manually address remaining issues
  4. ✅ Test your project
  5. ✅ Update to Gradle 9

Learning More

Example Workflow

# 1. Start the tool
./gradlew libertyRun

# 2. Open browser
open http://localhost:9080

# 3. Analyze your project
# Enter: /Users/john/projects/my-app
# Click: Analyze Project

# 4. Review results
# Total Issues: 12
# Critical: 4
# Auto-Fixable: 10

# 5. Fix issues
# Click: Fix All Auto-Fixable Issues

# 6. Verify results
# Success: 10/10 issues fixed
# Backups created in project directory

# 7. Test your project
cd /Users/john/projects/my-app
./gradlew clean build test

# 8. Success! 🎉

Getting Help

Documentation

Support

Community

  • ⭐ Star the project on GitHub
  • 🔄 Share with your team
  • 🤝 Contribute improvements

FAQ

Q: Is it safe to use on production code? A: Yes, but always review changes and test thoroughly. Backups are created automatically.

Q: Can I undo changes? A: Yes, restore from the backup files created before each fix.

Q: Does it support Kotlin DSL? A: Not yet, but it's planned for a future release.

Q: Can I run it in CI/CD? A: Yes, you can integrate it into your pipeline. See CI/CD documentation.

Q: What if I have custom Gradle plugins? A: The tool focuses on core Gradle issues. Custom plugin issues may need manual review.

Q: Does it modify my source code? A: No, it only modifies Gradle build files (build.gradle, settings.gradle).

Ready to migrate? Start the server and begin your Gradle 9 journey! 🚀
⚡