deprecation-and-migration

Deprecation and Migration

Overview

"Code is a liability, not an asset." Every line of code carries ongoing maintenance cost. Deprecation and migration are how you manage that liability — removing what's no longer needed and upgrading what must evolve. Hyrum's Law applies: once systems have users, simple announcements aren't enough.

When to Use

• Bumping minSdk or targetSdk
• Migrating to a new library version (Room, Compose, Kotlin)
• Replacing deprecated Android APIs
• Removing legacy feature flags or dead code
• Migrating from XML to Compose
• Upgrading from Java to Kotlin in existing modules

Skip when: The code has no callers and can be deleted outright.

Core Process

Step 1: Decision Framework

1. Assess before deprecating:

Question	Impact
How many callers exist?	grep/find usages to count
Is there a replacement ready?	Never deprecate without an alternative
What's the maintenance cost of keeping it?	Security risk? Build complexity?
What's the migration cost?	Test effort, rollback risk
Is there a deadline? (security, API level)	Compulsory vs advisory

1. Deprecation types:
   • Advisory: Migration recommended but not required on a timeline
   • Compulsory: Hard deadline (security fix, API level requirement, Play Store policy)

Step 2: Deprecate with Guidance

1. Use Kotlin's @Deprecated with replacement:

@Deprecated(
    message = "Use TaskRepository.getTasks() with Flow instead",
    replaceWith = ReplaceWith(
        expression = "getTasks()",
        imports = ["com.example.data.TaskRepository"]
    ),
    level = DeprecationLevel.WARNING  // WARNING → ERROR → HIDDEN
)
suspend fun getTaskList(): List<Task> = getTasks().first()

1. Deprecation levels:

   • WARNING — compile-time warning, still usable
   • ERROR — compile-time error, forces migration
   • HIDDEN — invisible in IDE, only for binary compatibility

2. Progression:

   Phase 1: Add @Deprecated(WARNING) + replacement guidance
   Phase 2: Migrate all internal callers
   Phase 3: Escalate to @Deprecated(ERROR)
   Phase 4: Remove (or HIDDEN for library backward compatibility)