Dependency Deprecation Pattern

Experiment Overview

| Item | Details | |------|---------| | Date | 2025-12-11 | | Goal | Remove Java/Maven/FIJI/CLIJ2 dependencies from KINTSUGI while maintaining backward compatibility | | Environment | Python 3.10+, cross-platform (Windows/Linux/macOS) | | Status | Success |

Context

KINTSUGI originally depended on Java/Maven for PyImageJ and CLIJ2 GPU processing. This created installation friction and cross-platform issues. The goal was to replace these with pure Python implementations (CuPy/NumPy) while allowing legacy users to continue using Java if needed.

Verified Workflow

Step 1: Identify all dependency touchpoints

Search for all references to the dependency:

# Search code
grep -r "java\|Java\|FIJI\|fiji\|clij\|CLIJ\|maven\|Maven\|ImageJ\|imagej" src/ notebooks/

# Check configuration files
grep -r "java\|openjdk\|maven" envs/ pyproject.toml

Files typically affected:

pyproject.toml - optional dependencies
envs/*.yml - conda environment files
src/*/deps.py - dependency checker
docs/*.md - documentation
Core modules using the dependency

Step 2: Update the core module with deprecation

# Example: edf.py - deprecating CLIJ2 backend

import warnings
from typing import Literal

BackendType = Literal["auto", "cupy", "numpy", "clij2"]

def _detect_backend(self, requested: BackendType) -> str:
    """Detect best available backend."""
    if requested == "clij2":
        warnings.warn(
            "CLIJ2 backend is deprecated and will be removed in v2.0. "
            "Use 'cupy' or 'numpy' instead.",
            DeprecationWarning,
            stacklevel=2
        )
        # Still allow it to work for now
        if self._check_clij2_available():
            return "clij2"
        else:
            warnings.warn("CLIJ2 not available, falling back to cupy")
            requested = "auto"

    if requested == "auto":
        # NEW priority order: CuPy > NumPy (CLIJ2 excluded from auto)
        if self._check_cupy_available():
            return "cupy"
        return "numpy"

    return requested

Step 3: Update dependency checker

# deps.py - mark as deprecated but keep functional

def _check_java(self, verbose: bool):
    """Check Java installation.

    .. deprecated::
        Java/Maven dependencies are no longer required for core functionality.
        Kept for backward compatibility with legacy CLIJ2 workflows.
    """
    if verbose:
        print("\n[Java/Maven] (DEPRECATED - no longer required)")

    # Still check and report, but don't fail
    try:
        # ... existing check code ...
        if verbose:
            print(f"  [OK]       java v{version} (optional)")
    except Exception as e:
        if verbose:
            print(f"  [SKIP]     java (optional, not required)")

Step 4: Update pyproject.toml

[project.optional-dependencies]
# Keep the optional group but exclude from [full]
java = [
    "JPype1>=1.5.0",
    "scyjava>=1.0.0",
    "pyimagej>=1.4.0",
]

# Remove java from full install
full = [
    "kintsugi[gpu,viz,dl,analysis,bio]",  # Note: java excluded
]

Step 5: Update environment files

# envs/env-*.yml - comment out with deprecation note

# Java/ImageJ Integration (DEPRECATED - no longer required)
# Uncomment if you need legacy CLIJ2 support:
# - openjdk=11
# - maven
# - jpype1

Step 6: Update documentation

Add deprecation notices to all relevant docs:

> **Note:** Java, Maven, and FIJI are no longer required. KINTSUGI now uses
> pure Python implementations (CuPy/NumPy) for all processing including EDF.

For historical documents, add a header:

> **DEPRECATION NOTICE (2025):** This document is historical. Java/Maven/FIJI
> dependencies have been removed. See `src/kintsugi/edf.py` for current implementation.

Failed Attempts (Critical)

| Attempt | Why it Failed | Lesson Learned | |---------|---------------|----------------| | Removing code completely | Broke existing user workflows | Keep deprecated code functional | | Silent removal | Users confused when code stopped working | Always emit deprecation warnings | | Keeping in [full] install | Users still got Java install failures | Exclude from aggregate installs | | No migration path | Users didn't know what to use instead | Document the replacement clearly |

Key Insights

Gradual deprecation: Mark as deprecated first, remove in next major version
Keep it working: Deprecated doesn't mean broken - users need time to migrate
Clear warnings: Use Python's warnings.warn() with DeprecationWarning
Document the alternative: Every deprecation notice should say what to use instead
Update ALL touchpoints: Code, configs, docs, environment files, README
Test both paths: Verify deprecated code still works AND new code works

Checklist for Dependency Deprecation

[ ] Search entire codebase for dependency references
[ ] Add deprecation warnings to code using the dependency
[ ] Update auto-detection to prefer new implementation
[ ] Keep optional dependency group but exclude from [full]
[ ] Comment out in environment files with explanation
[ ] Update installation documentation
[ ] Add deprecation notices to historical docs
[ ] Update CLAUDE.md / project documentation
[ ] Test deprecated path still works
[ ] Test new path works
[ ] Update changelog/release notes

References

Python deprecation warnings: https://docs.python.org/3/library/warnings.html
Semantic versioning for breaking changes: https://semver.org/
PEP 387 - Backwards Compatibility Policy: https://peps.python.org/pep-0387/