How Do You Track API Compatibility Rules for JetBrains Plugins?

IntelliJ Platform
1

Maintaining a plugin across multiple IntelliJ Platform versions can be challenging, especially when APIs gradually move from public to internal, become deprecated, or change their compatibility guarantees.

I’m curious how other plugin authors keep track of these changes.

For example, do you have automated checks for:

  • Use of internal APIs
  • Deprecated APIs
  • ApiStatus annotations
  • Binary or source compatibility
  • Required platform versions
  • Breaking API changes
  • Plugin dependencies
  • Compatibility across multiple IDE releases

I’m particularly interested in what happens before a plugin release.

Ideally, I’d like CI to be able to tell me something like:

“This plugin still builds, but it now depends on an API that isn’t considered stable for the target platform.”

For teams maintaining several plugins or supporting multiple IDE versions, do you use custom Gradle checks, IntelliJ Platform tooling, static analysis, or another API governance tool?

How much of API compatibility can realistically be automated today?

I’d also be interested in hearing how others distinguish between a genuine breaking change and a change that is technically source-incompatible but still safe for existing plugin binaries.

2

Most of cases are already covered by Plugin Verifier and ./gradlew verifyPlugin command.

At the same time, Marketplace also runs Plugin Verifier for all plugin builds and provides reports in admin UI for plugin developers.

IntelliJ IDEA also highlights deprecated and Internal APIs right away in code.

3

Indeed, this is covered by IntelliJ Plugin Verifier.

That verifier can be used:

  • as a standalone CLI tool
  • as a part of IntelliJ Platform Gradle Plugin - a recommended way to build plugins

There is a YouTube video covering the Plugin Verifier in details, with use-cases.