Design unified platform version compatibility abstraction

[meanmail]

Overview

The plugin supports multiple IntelliJ Platform versions (252, 253+) but uses three different compatibility approaches inconsistently across 13 language modules. This creates maintenance burden and confusion.

Problem

Current compatibility strategies:

1. BACKCOMPAT comments with deprecated APIs (e.g., PyCourseProjectGenerator.kt:74)
2. Branch-specific source overrides (branches/252/, branches/253/)
3. Runtime checks with ApplicationInfo.getInstance().build

Each approach is used in different places without clear guidelines on when to use which strategy.

Affected Areas

• All 13 language modules: hs-Java, hs-Kotlin, hs-Python, hs-Rust, hs-Cpp, hs-Go, hs-Php, hs-JavaScript, hs-Scala, hs-Shell, hs-sql, hs-CSharp
• Platform-specific utility files: intellij-plugin/hs-Python/branches/252/src/com/jetbrains/edu/python/learning/compatibilityUtils.kt
• Core modules with platform API usage

What Makes This Hard

1. Multiple strategies: Need to decide when each approach is appropriate
2. Module architecture: 13+ language modules each with their own compatibility needs
3. Build system complexity: Gradle convention plugins handle branch-specific sources
4. API evolution: Platform APIs change unpredictably between versions
5. Testing coverage: Must verify functionality on all supported platform versions
6. Migration path: Need clear strategy for when/how to drop old platform versions
7. Developer experience: New contributors need clear guidelines

Requirements

• Analyze all existing compatibility code and categorize current approaches
• Design a unified compatibility abstraction layer with clear decision criteria
• Create a decision tree/guidelines for when to use each approach:
  • When to use deprecated APIs with BACKCOMPAT
  • When to use branch-specific overrides
  • When to use runtime checks
  • When to create compatibility utility functions
• Refactor 2-3 complex compatibility cases as reference examples
• Document the pattern comprehensively for other developers
• Consider tooling to detect when new compatibility handling is needed
• Create migration guide for dropping platform version support
• Must not break existing functionality on any supported platform (252, 253)

Success Criteria

• Clear, documented strategy for platform compatibility
• Working reference examples of each approach
• Guidelines integrated into CLAUDE.md or new COMPATIBILITY.md
• All existing compatibility code still works
• Reduced cognitive load for future compatibility work

Estimated Time

6-7 hours (includes analysis, design, refactoring examples, documentation)