How do we know which editor version is used by users? How do we ship plugins that support multiple APIs?

Answered

Hi all!

We are developing a plugin https://plugins.jetbrains.com/plugin/18944-symflower-beta- that we want to equip with some newer features that use the "CodeVision" feature. However, before we can release the first iteration of these features we were baffled that we cannot disable the feature, if the API does not exist with a version. So we have some questions which we could not answer with existing documentation or questions of this forum.

- a. https://github.com/JetBrains/intellij-community/blob/master/platform/lang-impl/src/com/intellij/codeInsight/codeVision/CodeVisionProvider.kt is marked as "experimental. However, how does one identify which API was introduced with which version? It seems that the only chance one has is to look at the Git history and figure out the version somehow through that history?

- b. Does experimental mean, that the API is still changing? What happens when the API changes, are then all releases broken that use the old API?

- c. We shortly tried with IntelliJ 2021 which seems to not have the CodeVision API, and did not even build. So the question is open for us, how do we release multiple versions of our plugin, that allow different API usages? Or in other words: How can we disable feature A if version X does not provide the API for featuer A?

- d. All of that made us wonder how to figure out which versions of IntelliJ(and Goland, and ...) are currently used by a plugin? In the analytics of the plugin administration one can see metrics about the type of editor (IntelliJ, Goland, ...) but not for the versions. Where can one find that information?

- e. Can one say that in the end a user should update/upgrade anyway? And we should not care about versioning of the editor?

I think these questions are also interesting to other plugin developers, as one should be very careful not to break functionality for existing users.

Thanks so much and cheers,
Markus

3 comments
Comment actions Permalink

Guten Tag!

a) Make sure "Preferences | Build, Execution, Deployment | Build Tools | Gradle" option "Download external annotation for dependencies" is checked. Reimport Gradle project. Generated @AvailableSince annotations will then be available for platform sources in IDE when "Preferences | Editor | Inlay Hints" option "Annotations / Java / External annotations" is checked. (TBD I cannot make this work in my test project). Otherwise, indeed Git History is the safest choice. Notable new  API - usually once it has left Experimental status - is also announced in Docs https://plugins.jetbrains.com/docs/intellij/api-notable.html

b) It can change. It does not necessarily. Stability is unpredictable. Basically, one must expect breaking changes when using such API for future releases. https://github.com/JetBrains/java-annotations/blob/master/common/src/main/java/org/jetbrains/annotations/ApiStatus.java#L34

c) You will need to build specific versions of your plugin each targeting the minimum supported version in which a new feature/API is available. It is not possible to mark plugin descriptors as version-dependent. Usually, most plugin developers use dedicated branches.

d) https://plugins.jetbrains.com/docs/marketplace/product-versions-in-use-statistics.html

e) Technically it depends on your userbase (especially in closed environments), but as per link from d) indeed most users have rather recent IDE version installed.

0
Comment actions Permalink

Guten Abend!

Thanks so much Yann, we are still discussing on how we can support multiple versions. It would be great if this could be simplified somehow. But since we want to bring these features https://symflower.com/en/company/blog/2022/test-review-workflow/ to our JetBrains plugins we kind of need to adopt the experimental API.

I have another question: f.) are breaking changes, even for experimental APIs, announced somewhere? I am subscribed to some newsletters but i want to make sure that our team is on top of changes when we go the experimental API way.

0
Comment actions Permalink

I'm afraid, using branches targeting specific releases is really the best and safest option.

Incompatible changes are listed here https://plugins.jetbrains.com/docs/intellij/api-changes-list.html. As stated on the page, we do not announce changes in Experimental API, it is unsafe "by design".

Make sure to use Plugin Verifier and inspections in the IDE to be aware of any problems before uploading a possibly broken plugin to Marketplace: https://plugins.jetbrains.com/docs/intellij/verifying-plugin-compatibility.html

0

Please sign in to leave a comment.