Request to clarify API backward compatibility policy
Lately, there are a lot of code changes and API changes that affect backward compatibility both for plugins built with previous IDE versions and incompatibility of plugins built with latest 2020.1 EAP not being able to run on 2019.3 release.
I would love to know what is the official policy/philosophy for backward compatibility because not having a clear picture creates false expectations and frustration when these expectations are not met.
If the official policy is: a plugin must be built with a major IDE version for which it is intended, then no backward/forward compatibility can be assumed and plugins will need to have a code stream for each major release of the IDE.
In this case it is simple for plugin developers and JetBrains because no backward compatibility is to be expected. JetBrains can evolve the API and plugin developers are expected to have a separate stream of plugin sources for each major release, with plugins built by the IDE version for which they are intended.
On the other hand, if the policy is to ensure API compatibility for at least a couple of releases then this complicates API evolution and creates complications where inadvertent API changes cause plugins to break where they are not expected.
The reason I ask for clarification is I want to have a clear picture of what issues are my problem and what issues are to be reported as API change issues.
I have two issues on YouTrack, both of which are API forward compatibility related. Plugins built with new API will not run on 2019.3.
IDEA-230489 is caused by UI Designer form generated setup code using DynamicBundle to get string property text from resource bundle. This causes plugin forms built with 2020.1 to fail on 2019.3. This one appears to be in process of being addressed, although it is still not resolved.
IDEA-231419 is caused by change of NotificationGroup to Kotlin with default constructor arguments and @JvmOverloads which creates constructor signature incompatible with previous releases and results in plugin exception when invoked from Kotlin code.
Both of these issues are conceptually the same with minimal code changes to maintain compatibility. Yet, in one case the issue is in progress to be resolved in the other it is closed because:
It is not a good idea to build plugin with one version and then bundle it to previous versions. If you need to build plugin for 2019.3 — build it using 2019.3 to ensure that used API is present in 2019.3. If you cannot do this because of some other API incompatibilities — I would prefer to fix such incompatibilities.
The inconsistency is frustrating and confusing. It is also potentially creating unnecessary work on your side if no backward compatibility is to be expected.
Depending on the policy, developers have to expect different maintenance efforts for plugins because in one case a plugin is expected to work across a few releases with a single code stream. In the other, source code must be split into three streams per year to match the JetBrains IDE release schedule with corresponding three plugin releases per year to match.
I think official clarification will go a long way to put plugin developers and IDE developers on the same page and reduce superfluous issues and efforts caused by not having consistent expectations.
Please sign in to leave a comment.
UI Designer code generation is built ("hardcoded") into the IDE itself, so indeed it should be made compatible.
The second issue is about API compatibility of the chosen target platform, which should always be set to the minimum supported version of the plugin. Please note, API compatibility here is much wider than just the IJ Platform APIs we control, but it also includes all bundled libraries which receive regular (possibly breaking) updates as well.
Yann Cebron, the point I was bringing up is the inconsistency regardless of plausible justifications.
If the second issue does not allow to build plugins for an older IDE then there is no point in resolving the first issue because the IDE will still not be useable to create a plugin for an older IDE, no matter how the issue is resolved.
Why not drop the pretence of being able to use a new IDE to build plugins for an older IDE? This will remove the extra effort for your developers and the expectation by plugin developers that they can expect to build and share a plugin across different IDE builds.
This was possible in 2019.1 and earlier with some effort and reflection, but since 2019.2, the changes require a plugin built for and by the IDE for which it is intended.
My point is if this is the de-facto reality, why not make it official and remove confusion, false expectations and extra pointless effort?
It has always been possible to use a newer IDE version when targeting an older platform in your plugin project. IDEA-230489 is a bug and will be fixed, so it will work in 201 again.
If IDEA-231419 is not a bug and is not addressed then plugin using notification group built with 2020.1 will not run in 2019.3.
This is what I meant by consistency.
I have split my plugin into a separate source streams per IDE release and just build each version by the IDE for which it is designed.
IDEA-231419 is about the target platform chosen to compile against, not the IDE version used to build the plugin. Choosing 2019.3 as target platform version should allow running it in 2020.1 and following versions, unless there's a known (and documented) binary incompatibility in later versions.