Drop Platform Support

Drop Platform Support Skill

This skill runs the whole process of removing support for an old IntelliJ platform version in the JetBrains Academy plugin.

This skill implements the "Dropping the old platform version" section of documentation/different-platform-versions.md and adds more detail. If the two directly contradict each other, report the contradiction to the user.

Overview

Dropping platform support has three phases:

1. Remove platform-specific code for the old platform (steps 1–3)
2. Move remaining platform-specific code (that's identical across all supported platforms) to the main source set (steps 1–3)
3. Fix BACKCOMPAT comments and version checks that reference the old platform version (steps 4–6)

helpers/drop_platform_support_local.py automates most of phases 1 and 2. It does not move a file if a file with the same path already exists in the main source set. Those files stay in branches/<remaining>/ and have to be merged by hand. Phase 3 is done by the agent.

Arguments

The platform version to drop is the one the user asked for, referred to below as {platform_version} (e.g. 261). Its dotted form is {dotted_version} (e.g. 2026.1, see below). If the user did not give a version, ask. Do not guess.

Version naming

Platform versions appear in two forms. BACKCOMPAT comments in this repository use the dotted form. To convert: NNN → 20 + first two digits + . + last digit.

The same conversion is Project.platformVersion in buildSrc/src/main/kotlin/intellijUtils.kt.

Prerequisites

• Python 3 (python3), run from the repository root
• No nested worktrees or checkouts inside the repository (e.g. .claude/worktrees/*). The script walks the whole tree with os.walk(".") and would change their branches/ directories too.
• No staged or unstaged changes to tracked files (untracked files are fine). The script's changes are committed with git add -u, so any unrelated change to a tracked file would end up in the commit.
• A YouTrack ticket ID for the commits (ask the user if it isn't known — do not commit EDU-XXXX)

Instructions

1. Prepare the branch

• Check the current branch: git rev-parse --abbrev-ref HEAD
• If it is already drop-{platform_version}, continue on it. If that branch exists locally, switch to it with git checkout drop-{platform_version}. Otherwise create it: git checkout -b drop-{platform_version}.
• drop-{platform_version} is the same branch name the CI script (helpers/drop_platform_support.py) pushes. Check for a remote branch with git ls-remote --heads origin drop-{platform_version}. If one already exists, tell the user and ask whether to continue on it rather than creating a separate local one.
• Make sure there are no changes to tracked files before continuing.

2. Run the script

• From the repository root: python3 helpers/drop_platform_support_local.py --platform_version={platform_version}
• It deletes branches/{platform_version}/, moves files that are identical in every remaining branches/<v>/ directory into the main source set, deletes gradle-{platform_version}.properties, and updates the supported values line in gradle.properties.
• If the script fails partway, the tree is left half-applied. Stop, show the user git status, and ask how to proceed. Don't try to "finish" the changes by hand.
• Review the result with git status, then commit it with the ticket ID: git add -u && git commit -m "<ticket>: Drop {platform_version} support".

3. Check what the script did not do

• gradle.properties: The script only rewrites the supported values line when {platform_version} is the first entry, and it never touches environmentName. Check that:
  • {platform_version} no longer appears in # supported values: ...
  • environmentName is not {platform_version} (if it is, set it to a remaining version)
• Leftover platform-specific files: List everything still under */branches/*/ (e.g. find . -path '*/branches/*' -type f -not -path '*/build/*' -not -path './.git/*' -not -path './.claude/*'). For each file that exists in every remaining version but was not moved (because the main source set already has a file at that path), merge it by hand. The script removes only the immediate parent directory of deleted files, so review and then delete empty directories left behind: find . -path '*/branches/*' -type d -empty -not -path './.git/*' -not -path './.claude/*' -delete.
• Always platform-specific modules: the script deliberately leaves the remaining branches/<v>/ of the modules in ALWAYS_PLATFORM_SPECIFIC_MODULES (helpers/platform_support_common.py, e.g. intellij-plugin/integration-tests) untouched. Don't move, merge, inline, or simplify those files, even if only one platform is left.
• Only one platform left: This is the usual case, since the plugin normally supports two versions. With one version left, the script moves every file from its branches/<v>/ whose path doesn't already exist in main. Then also (except for the always platform-specific modules above):
  • inline *platform*.xml files pulled in with xi:include into the main XML, if any remain (e.g. educational-core-platform.xml included from educational-core.xml). Put the content exactly in place of the xi:include line and don't reorder the other entries
  • simplify compat shims that now have a single implementation (compatibilityUtils.kt functions, *Base classes, typealiases) — see "Tips and tricks" in the platform document
  • keep the branches/$environmentName/... source dirs in buildSrc/src/main/kotlin/intellij-plugin-common-conventions.gradle.kts: they are needed again when the next platform is added
• Commit any fixes from this step separately, or fold them into the phase 3 commit.

4. Determine the next oldest version

• Read the supported values line in gradle.properties after step 3.
• The next oldest version is the smallest remaining one. Example: when dropping 261 and supported values: 262, 263 remain, the next oldest is 262.

5. Find BACKCOMPAT comments and version checks

Prefer JetBrains MCP tools (search_regex, search_text, search_symbol). Fall back to grep.

• Primary: BACKCOMPAT comments with the dotted version. The colon is optional in this repo (both BACKCOMPAT: 2026.1 and BACKCOMPAT 2026.1 exist): grep -rnE "BACKCOMPAT:? *{dotted_version}" --exclude-dir=build --exclude-dir=.git --exclude-dir=localization --exclude-dir=.claude . (escape the dot, e.g. 2026\.1). Don't restrict file types — BACKCOMPAT notes appear in .kt, .java, .kts, .xml, .properties, .py, .md, etc. .claude/ is excluded on purpose. The examples in this skill use real versions, so don't edit them as part of the drop.
• Secondary: the numeric form (BACKCOMPAT.*{platform_version}) and bare BACKCOMPAT comments with no version that mention the dropped platform.
• Older versions: BACKCOMPAT comments for versions older than {platform_version} can be left over from past drops. Fix them if they are simple. Otherwise list them in the summary for the user. Don't skip them silently.
• Version checks for the next oldest version only (these are now always true):
  • build scripts: isAtLeast{NextOldestVersion} (defined in buildSrc/src/main/kotlin/intellijUtils.kt, used in intellij-plugin/**/build.gradle.kts and buildSrc). Use search_symbol to find all usages.
• Runtime and test checks for any version ≤ the next oldest version (always true or always false):
  • runtime: search BuildNumber\.fromString\("[0-9]{3} — this covers named constants (BUILD_242) and inline checks (build < BuildNumber.fromString("252")!!) compared with ApplicationInfo.getInstance().build. Checks for versions older than {NextOldestVersion} are leftovers from past drops. Treat them the same way as older BACKCOMPAT comments: fix them if simple, otherwise report them.
  • tests: @MinPlatformVersion("...") whose version is ≤ the next oldest version (intellij-plugin/educational-core/testSrc/com/jetbrains/edu/rules/ConditionalExecutionRule.kt)
• Leave checks for newer versions alone. Example: when dropping 261 with 262 and 263 remaining, remove isAtLeast262, but leave isAtLeast263 alone — it still distinguishes 262 from 263.
• Final sweep: plain-grep for \b{platform_version}\b and {dotted_version} (excluding branches/, build, .git, .claude, localization, and test data), and review the hits by hand. This catches hard-coded values like environment("IDEA_BUILD_NUMBER", "261"). Don't auto-fix anything here. Many hits are legitimate, e.g. dependency versions such as psiViewerPlugin=PsiViewer:2026.1 in gradle-262.properties or release history in documentation/PluginVersionsInfo.md.