Migration: Boilerplate Reduction

Summary

Incrementally modernize the project by:

• Migrating Maven → Gradle
• Introducing Kotlin
• Replacing boilerplate in models and requests

Strict requirement: No breaking changes to public API.

Execution Rules

• Work in small, reviewable commits
• Each step must:
  • Compile successfully
  • Pass all tests
• Do NOT combine phases in a single commit
• Prefer incremental migration over large rewrites
• Maintain Java ↔ Kotlin interoperability at all times

Phase 1: Gradle Migration

Tasks

• Create build.gradle.kts
• Port dependencies from pom.xml
• Add required plugins (java, jacoco, publishing)
• Keep existing directory structure
• Update CI to use Gradle

Checkpoint

• ./gradlew build succeeds
• All tests pass

Commit Boundary

• chore: migrate build system from Maven to Gradle

Phase 2: Enable Kotlin

Tasks

• Add Kotlin plugin and stdlib
• Verify mixed Java/Kotlin compilation works

Checkpoint

• Project builds with Kotlin enabled
• No functional changes

Commit Boundary

• chore: add Kotlin support to project

Phase 3: Model Migration (Incremental)

Tasks

• Convert model classes to a Kotlin representation in small batches, respecting this library's public API stability as described by jakewharton.com/public-api-challenges-in-kotlin.
• Use kotlinx.serialization for JSON handling
• Remove custom JSON utilities only for migrated models

Execution Strategy

• Start with simple, dependency-free models
• Progress to dependent and complex models

Per-Batch Checkpoint

• Build succeeds
• Serialization/deserialization tests pass
• No API breakage

Commit Boundaries (repeat per batch)

• refactor(models): convert <ModelName> to Kotlin data class

Phase 4: Request Layer Simplification

Tasks

• Introduce a mechanism to reduce request boilerplate:
  • Option A: Code generation
  • Option B: Shared abstractions/annotations
• Apply incrementally to request classes

Execution Strategy

• Start with simplest request classes
• Migrate complex ones later

Per-Batch Checkpoint

• Requests produce identical HTTP behavior
• Tests pass

Commit Boundaries (repeat per batch)

• refactor(requests): simplify <RequestName> implementation

Phase 5: Remove Remaining JSON Boilerplate

Tasks

• Eliminate remaining custom JSON parsing
• Centralize common behavior if needed

Checkpoint

• All JSON fixtures deserialize correctly
• No regressions

Commit Boundary

• refactor: remove remaining JSON utility boilerplate

Phase 6: Kotlin Conversion (Core)

Tasks

• Convert core classes (API entry point, base request classes, utilities) to Kotlin
• Improve readability using Kotlin features (null safety, defaults)

Checkpoint

• Public API unchanged
• Full test suite passes

Commit Boundaries

• refactor(core): convert core classes to Kotlin

Phase 7: Tests & Quality

Tasks

• Migrate test utilities to Kotlin (optional but preferred)
• Improve readability and reduce duplication
• Ensure coverage is maintained or improved

Checkpoint

• All tests pass
• Coverage ≥ previous baseline

Commit Boundary

• test: modernize and clean up test suite

Phase 8: Documentation & Release

Tasks

• Update README (Gradle + Kotlin usage)
• Document contribution workflow
• Prepare release notes

Checkpoint

• Docs reflect new setup accurately

Commit Boundary

• docs: update documentation for Kotlin + Gradle migration

Final Validation

• Full build passes
• All tests pass
• No public API changes
• Artifacts publish successfully

Guidance

• Prefer safe refactors over clever optimizations
• If uncertain, keep existing behavior unchanged
• Avoid large diffs; split work into minimal steps
• Validate continuously after each change