Handling IntelliJ updates

Overview

When JetBrains release an update to IntelliJ IDEA, it is possible that the plugin stops working. This almost never happens in case of minor (silent) updates, however when an update changes the major version (e.g. 2020.3 -> 2021.1 or 2021.1 -> 2021.2), then it is probable that the plugin will outright refuse to even install.

What to do

Updating IntelliJ SDK

A new IntelliJ version means that A+ Courses might have to bump the required IDE version. This is very easy:

1. Locate the version variable inside build.gradle
2. Set it to the version of the current IntelliJ release.

Scala plugin version incompatibility

The most common cause for incompatibility is the Scala plugin version. Very often the new IntelliJ version requires a newer version of the Scala plugin than the A+ Courses plugin does. In such case the solution is simple:

1. Browse all versions of Scala plugin on the JetBrains page
2. Copy the latest compatible version into the plugins variable inside build.gradle
3. Rebuild the plugin

If the latest Scala plugin version does not work for some reason, try again from step 1. and use the next older version from the list. There is always at least one version which will work with both the plugin and the IDE simultaneously.

Gradle's runIde runs older version of IntelliJ

This is caused by the version string that is located inside plugin.xml. To update it, follow these steps:

1. Locate the XML tag idea-version inside plugin.xml
2. Update the since-build entry to the latest IntelliJ version
3. Run Gradle's clean action

After these steps, runIde will now use the latest IntelliJ version.

Manual testing

An update to IntelliJ usually warrants releasing a new version of A+ Courses. This means that a full manual testing cycle should be conducted, during which other incompatibilities might be revealed. If this happens, appropriate fixes in the code must be done.

To avoid introducing code that breaks when IntelliJ updates, methods and classes marked as internal or deprecated should not be used.

Tutorials (IDE activities) should also be manually and extensively tested with emphasis on presenters. This is because presenters might take advantage of IntelliJ's implementation details (component class names, layout tree etc.) and these can change between versions.

IntelliJ IDEA EAP

Early Access Program is IntelliJ's system of pre-release IDE versions. Before a major update, IntelliJ might release such an EAP version for plugin developers. This can be leveraged to test compatibility before a newer IntelliJ version is released to the public.

In order to use EAP versions directly through Gradle's runIde task, one should locate the updateSinceUntilBuild = false line inside build.gradle and delete it. Removing this line will cause Gradle to always assume the latest possible IntelliJ version. This, however, might not always be desirable during development (random updates are confusing) - therefore that variable should be false in production.