Migrating sbt plugins to sbt 2 with sbt2-compat plugin

"sbt 2 is a major upgrade from sbt 1 and makes breaking changes on the API level. As a plugin maintainer, you want to preserve compatibility with sbt 1 when migrating - so you want to cross-publish your plugin for sbt 1 and sbt 2. Ideally, you want to have the same codebase that compiles for both sbt 1 and sbt 2."

"In sbt 1, everything is a java.io.File, whereas in sbt 2 the types are more granular depending on the context. For example, HashedVirtualFileRef is used for classpath entries, VirtualFile - for task outputs and caching artifacts, VirtualFileRef - for path-like references. These types are defined in the xsbti package."

"The current approach to handling these discrepancies is to have a single codebase that compiles for both sbt 1 and sbt 2, and use the PluginCompat pattern to provide a compatibility layer. You would then be able to define the task using this unified API."

sbt 2 introduces breaking API changes from sbt 1, requiring plugin authors to adapt their code. A community-driven effort supports plugin ecosystem migration through cross-publishing capabilities. The sbt2-compat plugin facilitates this transition by implementing the PluginCompat pattern, which abstracts version-specific differences into a compatibility layer. A key example involves file type representations: sbt 1 uses java.io.File uniformly, while sbt 2 employs granular types like HashedVirtualFileRef, VirtualFile, and VirtualFileRef from the xsbti package. Plugin maintainers can maintain a single codebase that compiles for both versions by defining version-specific abstractions and using them through a unified API, enabling seamless cross-publishing.

Read at Scala-lang