Deprecated API Updater

Deprecated API Updater

Systematic detection and migration of deprecated API calls across codebases. This skill covers deprecation detection techniques, migration mapping strategies, automated rewriting approaches, framework-specific update guides, and validation procedures to ensure that updated code behaves identically to the original.

When to Use This Skill

Use this skill for:

• Upgrading a framework or library to a new major version with breaking changes
• Resolving deprecation warnings before they become errors in a future release
• Migrating from one library to a replacement library (e.g., moment.js to date-fns, requests to httpx)
• Updating code after a language version upgrade (Python 2 to 3, Java 8 to 17, Node.js LTS upgrades)
• Cleaning up technical debt caused by accumulated deprecation warnings
• Preparing for removal of deprecated features announced in release notes
• Auditing a codebase for end-of-life (EOL) dependency usage

Trigger phrases: "deprecated", "deprecation warning", "update API", "migrate API", "upgrade library", "breaking changes", "deprecated method", "EOL", "version upgrade", "migration guide", "update deprecated calls"

What This Skill Does

This skill provides an end-to-end deprecation migration workflow:

• Deprecation Detection: Identifies deprecated API usage through compiler warnings, static analysis, annotation scanning, and changelog analysis
• Migration Mapping: Creates mappings from deprecated APIs to their replacements, including parameter transformation rules
• Automated Rewriting: Applies migration mappings to rewrite code automatically where the transformation is mechanical
• Framework-Specific Guides: Provides migration patterns for common framework upgrades (React, Spring, Django, Express, etc.)
• Validation: Verifies that updated code produces the same behavior as the original through test execution and output comparison
• Risk Assessment: Evaluates the risk of each migration and recommends the order of operations

Instructions

Step 1: Detect Deprecated API Usage

Identify all deprecated API calls in the codebase using multiple detection methods.

Detection Methods

Python Example: Detecting Deprecated Usage

# Run with: python -W all your_script.py
# Or configure in code:
import warnings
warnings.simplefilter("always", DeprecationWarning)

# Common deprecated patterns in Python:

# 1. DEPRECATED: collections.MutableMapping (Python 3.9+)
from collections import MutableMapping  # DeprecationWarning
# REPLACEMENT:
from collections.abc import MutableMapping

# 2. DEPRECATED: datetime.utcnow() (Python 3.12+)
from datetime import datetime
now = datetime.utcnow()  # DeprecationWarning: use timezone-aware alternative
# REPLACEMENT:
from datetime import datetime, timezone
now = datetime.now(timezone.utc)

# 3. DEPRECATED: pkg_resources (in favor of importlib)
import pkg_resources  # DeprecationWarning in newer setuptools
version = pkg_resources.get_distribution("mypackage").version
# REPLACEMENT:
from importlib.metadata import version
ver = version("mypackage")

# 4. DEPRECATED: asyncio.get_event_loop() without running loop (Python 3.10+)
import asyncio
loop = asyncio.get_event_loop()  # DeprecationWarning
# REPLACEMENT:
loop = asyncio.new_event_loop()
# Or better: use asyncio.run() as the entry point

# 5. DEPRECATED: typing.Optional, typing.List, typing.Dict (Python 3.9+)
from typing import Optional, List, Dict
def process(items: List[str], config: Optional[Dict[str, int]] = None): ...
# REPLACEMENT: use built-in generics
def process(items: list[str], config: dict[str, int] | None = None): ...

JavaScript Example: Detecting Deprecated Node.js and React APIs

// Node.js deprecated APIs

// 1. DEPRECATED: url.parse() (use URL constructor)
const url = require("url");
const parsed = url.parse("https://example.com/path?q=1");  // DEP0169
// REPLACEMENT:
const parsed = new URL("https://example.com/path?q=1");

// 2. DEPRECATED: Buffer(size) constructor (security risk)
const buf = new Buffer(10);  // DEP0005
// REPLACEMENT:
const buf = Buffer.alloc(10);     // zero-filled
const buf2 = Buffer.from([1, 2]); // from data

// 3. DEPRECATED: fs.exists() (use fs.access or fs.stat)
const fs = require("fs");
fs.exists("/path", (exists) => { ... });  // DEP0103
// REPLACEMENT:
const fsPromises = require("fs").promises;
try {
    await fsPromises.access("/path");
    // file exists
} catch {
    // file does not exist
}

// React deprecated APIs

// 4. DEPRECATED: componentWillMount (React 16.3+)
class MyComponent extends React.Component {
    componentWillMount() { /* ... */ }  // UNSAFE, renamed
}
// REPLACEMENT:
class MyComponent extends React.Component {
    // Move logic to constructor or componentDidMount
    componentDidMount() { /* ... */ }
}
// Or better: convert to functional component with hooks
function MyComponent() {
    useEffect(() => { /* ... */ }, []);
}

// 5. DEPRECATED: ReactDOM.render (React 18+)
import ReactDOM from "react-dom";
ReactDOM.render(<App />, document.getElementById("root"));
// REPLACEMENT:
import { createRoot } from "react-dom/client";
const root = createRoot(document.getElementById("root"));
root.render(<App />);

Java Example: Detecting Deprecated APIs

// Compile with: javac -Xlint:deprecation *.java

// 1. DEPRECATED: Date/Calendar API (Java 8+)
import java.util.Date;
import java.util.Calendar;
Date now = new Date();
Calendar cal = Calendar.getInstance();
int year = cal.get(Calendar.YEAR);
// REPLACEMENT:
import java.time.LocalDate;
import java.time.LocalDateTime;
import java.time.Instant;
LocalDateTime now = LocalDateTime.now();
int year = LocalDate.now().getYear();
Instant instant = Instant.now();

// 2. DEPRECATED: Thread.stop(), Thread.suspend(), Thread.resume()
thread.stop();  // @Deprecated(since="1.2", forRemoval=true)
// REPLACEMENT: use interrupt() and cooperative cancellation
thread.interrupt();
// In the thread's run method:
if (Thread.currentThread().isInterrupted()) {
    return; // Clean exit
}

// 3. DEPRECATED: javax.* namespace (Jakarta EE 9+)
import javax.servlet.http.HttpServletRequest;
import javax.persistence.Entity;
// REPLACEMENT:
import jakarta.servlet.http.HttpServletRequest;
import jakarta.persistence.Entity;

// 4. DEPRECATED: finalize() method (Java 9+)
@Override
protected void finalize() throws Throwable { /* cleanup */ }
// REPLACEMENT: use try-with-resources or Cleaner
public class MyResource implements AutoCloseable {
    @Override
    public void close() { /* cleanup */ }
}

// 5. DEPRECATED: SecurityManager (Java 17+, removal in future)
System.setSecurityManager(new SecurityManager());
// REPLACEMENT: use module system and other security mechanisms

Step 2: Create Migration Mappings

For each deprecated API, define the mapping to its replacement.

Migration Mapping Structure

@dataclass
class MigrationMapping:
    deprecated_pattern: str          # Regex or AST pattern for the deprecated call
    replacement_template: str        # Template for the replacement code
    parameter_transform: dict        # How parameters map from old to new
    requires_import_change: bool     # Whether import statements need updating
    old_import: str                  # Import to remove
    new_import: str                  # Import to add
    notes: str                       # Special considerations
    risk_level: str                  # low, medium, high
    automated: bool                  # Whether this can be automated safely


# Example migration mappings
PYTHON_MIGRATIONS = [
    MigrationMapping(
        deprecated_pattern=r"datetime\.utcnow\(\)",
        replacement_template="datetime.now(timezone.utc)",
        parameter_transform={},
        requires_import_change=True,
        old_import="from datetime import datetime",
        new_import="from datetime import datetime, timezone",
        notes="Returns timezone-aware datetime instead of naive UTC",
        risk_level="medium",
        automated=True,
    ),
    MigrationMapping(
        deprecated_pattern=r"from collections import (.*?)(MutableMapping|MutableSequence|MutableSet)",
        replacement_template=r"from collections.abc import \2",
        parameter_transform={},
        requires_import_change=True,
        old_import="from collections import MutableMapping",
        new_import="from collections.abc import MutableMapping",
        notes="Abstract base classes moved to collections.abc",
        risk_level="low",
        automated=True,
    ),
]

Framework-Specific Migration Tables

React 17 to React 18 Migration:

Spring Boot 2.x to 3.x Migration:

Django 3.x to 4.x Migration:

Step 3: Apply Automated Rewrites

For migrations marked as "automated", apply the transformation systematically.

Python Example: Automated Migration Script

import re
import ast
from pathlib import Path
from typing import List, Tuple


class DeprecationMigrator:
    def __init__(self, migrations: List[MigrationMapping]):
        self.migrations = migrations
        self.changes_log: List[dict] = []

    def migrate_file(self, filepath: Path) -> Tuple[str, int]:
        """Migrate a single file. Returns (new_content, change_count)."""
        content = filepath.read_text()
        original = content
        change_count = 0

        for migration in self.migrations:
            if not migration.automated:
                continue

            # Count matches before replacement
            matches = re.findall(migration.deprecated_pattern, content)
            if matches:
                # Apply replacement
                content = re.sub(
                    migration.deprecated_pattern,
                    migration.replacement_template,
                    content
                )

                # Update imports if needed
                if migration.requires_import_change:
                    content = self._update_imports(
                        content,
                        migration.old_import,
                        migration.new_import
                    )

                change_count += len(matches)
                self.changes_log.append({
                    "file": str(filepath),
                    "pattern": migration.deprecated_pattern,
                    "matches": len(matches),
                    "risk": migration.risk_level,
                })

        return content, change_count

    def _update_imports(self, content: str, old_import: str, new_import: str) -> str:
        """Update import statements."""
        if old_import in content and new_import not in content:
            content = content.replace(old_import, new_import)
        return content

    def migrate_directory(self, directory: Path, dry_run: bool = True) -> dict:
        """Migrate all Python files in a directory."""
        total_changes = 0
        files_changed = 0

        for filepath in directory.rglob("*.py"):
            new_content, change_count = self.migrate_file(filepath)
            if change_count > 0:
                files_changed += 1
                total_changes += change_count
                if not dry_run:
                    filepath.write_text(new_content)
                print(f"{'[DRY RUN] ' if dry_run else ''}Updated {filepath}: "
                      f"{change_count} changes")

        return {
            "files_scanned": len(list(directory.rglob("*.py"))),
            "files_changed": files_changed,
            "total_changes": total_changes,
            "dry_run": dry_run,
        }

JavaScript Example: Automated Codemod with jscodeshift

// codemod: migrate-react-18.js
// Run with: npx jscodeshift -t migrate-react-18.js src/

module.exports = function transformer(fileInfo, api) {
    const j = api.jscodeshift;
    const root = j(fileInfo.source);
    let hasChanges = false;

    // Migration 1: ReactDOM.render() -> createRoot().render()
    root.find(j.CallExpression, {
        callee: {
            object: { name: "ReactDOM" },
            property: { name: "render" },
        },
    }).forEach(path => {
        const [element, container] = path.node.arguments;

        // Replace with createRoot pattern
        const createRootCall = j.callExpression(
            j.memberExpression(
                j.callExpression(j.identifier("createRoot"), [container]),
                j.identifier("render")
            ),
            [element]
        );
        j(path).replaceWith(createRootCall);
        hasChanges = true;
    });

    // Migration 2: Update import statement
    if (hasChanges) {
        // Remove old import
        root.find(j.ImportDeclaration, {
            source: { value: "react-dom" },
        }).forEach(path => {
            j(path).remove();
        });

        // Add new import
        const newImport = j.importDeclaration(
            [j.importSpecifier(j.identifier("createRoot"))],
            j.literal("react-dom/client")
        );
        root.find(j.Program).get("body", 0).insertBefore(newImport);
    }

    return hasChanges ? root.toSource() : fileInfo.source;
};

Java Example: Automated javax to jakarta Migration

import java.io.IOException;
import java.nio.file.*;
import java.util.*;

public class JakartaMigrator {

    private static final Map<String, String> PACKAGE_MAPPINGS = Map.of(
        "javax.servlet", "jakarta.servlet",
        "javax.persistence", "jakarta.persistence",
        "javax.validation", "jakarta.validation",
        "javax.annotation", "jakarta.annotation",
        "javax.inject", "jakarta.inject",
        "javax.transaction", "jakarta.transaction",
        "javax.ws.rs", "jakarta.ws.rs",
        "javax.json", "jakarta.json",
        "javax.websocket", "jakarta.websocket",
        "javax.mail", "jakarta.mail"
    );

    public record MigrationResult(
        int filesScanned,
        int filesModified,
        int totalReplacements,
        List<String> modifiedFiles
    ) {}

    public MigrationResult migrate(Path sourceDir, boolean dryRun) throws IOException {
        List<String> modifiedFiles = new ArrayList<>();
        int totalReplacements = 0;
        int filesScanned = 0;

        try (var stream = Files.walk(sourceDir)) {
            List<Path> javaFiles = stream
                .filter(p -> p.toString().endsWith(".java"))
                .toList();

            filesScanned = javaFiles.size();

            for (Path file : javaFiles) {
                String content = Files.readString(file);
                String updated = content;
                int replacements = 0;

                for (var entry : PACKAGE_MAPPINGS.entrySet()) {
                    String oldPkg = entry.getKey();
                    String newPkg = entry.getValue();

                    if (updated.contains(oldPkg)) {
                        int count = countOccurrences(updated, oldPkg);
                        updated = updated.replace(oldPkg, newPkg);
                        replacements += count;
                    }
                }

                if (replacements > 0) {
                    totalReplacements += replacements;
                    modifiedFiles.add(file.toString());
                    if (!dryRun) {
                        Files.writeString(file, updated);
                    }
                    System.out.printf("%s%s: %d replacements%n",
                        dryRun ? "[DRY RUN] " : "", file, replacements);
                }
            }
        }

        return new MigrationResult(filesScanned, modifiedFiles.size(),
            totalReplacements, modifiedFiles);
    }

    private int countOccurrences(String text, String pattern) {
        int count = 0;
        int idx = 0;
        while ((idx = text.indexOf(pattern, idx)) != -1) {
            count++;
            idx += pattern.length();
        }
        return count;
    }
}

Step 4: Handle Non-Automatable Migrations

Some deprecations require manual analysis because the replacement involves structural changes or behavioral differences.

Manual Migration Process

1. Document the change: write a brief description of what changed and why
2. Identify all call sites: find every place the deprecated API is used
3. Understand the behavioral difference: the replacement may have subtly different behavior (e.g., different default values, different error handling, different thread safety)
4. Migrate one call site at a time: change one usage, run tests, commit, then move to the next
5. Add tests for behavioral differences: if the replacement behaves differently in edge cases, add tests that verify the new behavior is acceptable

Example: Manual Migration (Spring Security)

// BEFORE: WebSecurityConfigurerAdapter (deprecated in Spring Security 5.7)
@Configuration
@EnableWebSecurity
public class SecurityConfig extends WebSecurityConfigurerAdapter {

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http
            .authorizeRequests()
            .antMatchers("/api/public/**").permitAll()
            .antMatchers("/api/admin/**").hasRole("ADMIN")
            .anyRequest().authenticated()
            .and()
            .httpBasic();
    }

    @Override
    protected void configure(AuthenticationManagerBuilder auth) throws Exception {
        auth.userDetailsService(userDetailsService)
            .passwordEncoder(passwordEncoder());
    }
}

// AFTER: Component-based configuration (cannot be automated due to structural change)
@Configuration
@EnableWebSecurity
public class SecurityConfig {

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/api/public/**").permitAll()
                .requestMatchers("/api/admin/**").hasRole("ADMIN")
                .anyRequest().authenticated()
            )
            .httpBasic(Customizer.withDefaults());
        return http.build();
    }

    @Bean
    public AuthenticationManager authenticationManager(
            AuthenticationConfiguration config) throws Exception {
        return config.getAuthenticationManager();
    }

    @Bean
    public UserDetailsService userDetailsService() {
        // Configure user details service
        return new CustomUserDetailsService();
    }
}

Step 5: Validate the Migration

After applying migrations, verify correctness through multiple validation layers.

Validation Checklist

1. Compilation/Parsing: the code compiles without deprecation warnings for migrated APIs
2. Unit tests pass: all existing unit tests pass without modification
3. Integration tests pass: all integration tests pass
4. No new deprecation warnings: the migration did not introduce new deprecation warnings
5. Behavioral equivalence: for high-risk migrations, verify output matches the pre-migration version
6. Performance comparison: for performance-sensitive APIs, benchmark before and after

Step 6: Generate the Migration Report

## Deprecated API Migration Report

### Summary
- **Codebase**: {project name}
- **Migration scope**: {what was upgraded -- library name and versions}
- **Files scanned**: {count}
- **Files modified**: {count}
- **Total API calls migrated**: {count}
- **Automated migrations**: {count} ({percentage})
- **Manual migrations**: {count} ({percentage})
- **Remaining deprecations**: {count}

### Migrations Applied
| # | Deprecated API | Replacement | Occurrences | Method | Risk |
|---|---------------|-------------|-------------|--------|------|
| 1 | {old API} | {new API} | {count} | Auto | Low |
| 2 | {old API} | {new API} | {count} | Manual | High |

### Validation Results
| Check | Status | Details |
|-------|--------|---------|
| Compilation | PASS/FAIL | {warnings/errors remaining} |
| Unit tests | PASS/FAIL | {count} passed, {count} failed |
| Integration tests | PASS/FAIL | {count} passed, {count} failed |
| Deprecation warnings | PASS/FAIL | {count} remaining |

### Remaining Items
{List of deprecations that could not be migrated automatically and require manual attention}

### Risks and Notes
{Special considerations, behavioral differences, or follow-up actions}

Best Practices

• Always run migrations in dry-run mode first: preview changes before applying them to understand scope and identify potential issues
• Migrate in focused batches: group migrations by library or framework and migrate one group per commit; this makes review and rollback manageable
• Update tests alongside production code: if the test code also uses deprecated APIs, update it in the same commit to keep tests consistent
• Check migration guides from library maintainers: official migration guides cover edge cases and behavioral changes that automated tools miss; always read them before starting
• Preserve git blame: use separate commits for mechanical migrations (import renames) and behavioral changes so that git blame remains informative
• Run the full test suite after each batch: do not accumulate multiple migration batches before testing; verify each batch independently
• Monitor deprecation warnings in CI/CD: configure CI to fail on new deprecation warnings so that deprecated API usage does not accumulate
• Schedule regular deprecation cleanup: quarterly or before major releases, audit and resolve accumulated deprecation warnings

Common Pitfalls

• Assuming deprecated APIs are drop-in replaceable: the replacement API may have different default values, different exception behavior, different nullability contracts, or different thread safety guarantees; always read the documentation
• Migrating deprecated APIs in code you do not own: third-party libraries may use deprecated APIs internally; do not modify vendor code; instead, upgrade the library to a version that has already migrated
• Applying regex-based replacements without understanding context: a simple find-and-replace of javax to jakarta may modify string literals, comments, or non-Java files incorrectly; use AST-based tools when possible
• Ignoring transitive dependencies: your code may not directly use a deprecated API, but a dependency might; dependency scanning tools help identify this
• Not testing with the target runtime version: running tests with the old runtime version does not verify that the migration works on the new version; test with both during the transition period
• Batch-migrating high-risk items: high-risk migrations (behavioral changes, structural rewrites) should be done one at a time with full verification; do not combine them with low-risk mechanical migrations
• Forgetting to update documentation and configuration: after migrating code, update README files, configuration examples, deployment scripts, and developer setup guides that reference deprecated APIs
• Not communicating the migration to the team: other developers may be working on code that uses the deprecated API; coordinate migrations to avoid merge conflicts and duplicated effort