Compatibility guarantee between different versions of Kotlin and subsystems

This page describes compatibility guarantees for different versions of Kotlin and subsystems.

Compatibility vocabulary

Compatibility means answering the question: for a given two versions of Kotlin (for example, 1.2 and 1.1.5), can code written for one version be used with the other? The list below explains the compatibility modes for different version pairs. Note that if the version number is smaller (even if it was released later than a larger version) the version is older. For “old” we use OV and for “new” we use NV.

• C— Fully compatibleCOmpatibility)
  • language
    • No syntax changes (Get rid of the bug*)
    • New warnings/prompts can be added or removed
  • API (kotlin-stdlib-*,kotlin-reflect-*)
    • There is no API changes
    • It is possible to add/remove bandsWARNINGLevel of deprecated items
  • Binary (ABI)
    • Runtime: Binary can be used interchangeably
    • Compilation: Binary is used interchangeably
• BCLALanguage and API backward compatibility (Backward Compatibility for the Language and API)
  • language
    • Deprecated syntax in OV may be removed from NV
    • In addition, all code that can be compiled in OV can be compiled in NV (bug free *)
    • New syntax may be added to NV
    • Some limitations of OV can be raised in NV
    • New warnings/prompts can be added or removed
  • API (kotlin-stdlib-*,kotlin-reflect-*)
    • New apis may be added
    • It is possible to add/remove bandsWARNINGLevel of deprecated items
    • WARNINGLevel of deprecation items may be promoted in NV toERRORLevel orHIDDEN 级
• BCB— Binary backward compatibility (Backward Compatibility for BInaries)
  • Binary (ABI)
    • Runtime: The binary of NV can be used anywhere the binary of OV works
    • NV compiler: Code compiled against the OV binary can be compiled against the NV binary
    • The OV compiler may not accept NV binaries (for example, binaries showing newer language features or apis)
• BC— Fully backward compatibleBackward COmpatibility)
  • BC = BCLA & BCB
• EXP— Experimental feature
  • See below
• NO— No compatibility guarantees
  • We will do our best to provide a smooth migration, but cannot give any guarantees
  • Plan migrations separately for each incompatible subsystem

Leaving bugs unchanged means that if an important bug is found (for example, in compiler diagnostics or elsewhere), fixing it may introduce a damaging change, but we are always very careful with such changes.

Compatibility guarantees for Kotlin distributions

Kotlin for the JVM:

• Patch version updates (e.g. 1.1.x) are fully compatible
• Later versions (for example, 1.x) are backward compatible

Kotlin for the JS platform: Starting with Kotlin 1.1, patch releases and minor updates provide backward compatibility (BCLA) for languages and apis, but no BCB.

Kotlin Scripts: Patch versions and minor version updates provide backward compatibility (BCLA) for languages and apis, but no BCB.

Cross-platform compatibility

Kotlin is available on multiple platforms (JVM/Android, JavaScript, and soon native platforms). Each platform has its own particularities (JavaScript doesn’t have proper integers, for example), so we have to adjust the language accordingly. Our goal is to provide reasonable code portability without sacrificing too much.

Each platform may have specific language extensions (such as the platform type of the JVM and dynamic typing of JavaScript) or restrictions (such as overload-related restrictions on the JVM), but the core language remains the same.

The standard library provides core apis that are available on all platforms, and we strive to make these apis work the same way on each platform. In addition, the library provides platform-specific extensions (for example, java.io for the JVM or JS () for JavaScript) and apis that can be called uniformly but work differently (for example, regular expressions for the JVM and JavaScript).

Experimental function

Experimental features, such as coroutines in Kotlin 1.1, can be exempted from the compatibility modes listed above. Such functionality requires opt-in to be used without compiler warnings. Experimental features are at least backward-compatible with patch updates, but we do not guarantee compatibility with any subsequent patch updates (migration assistance will be provided where possible).

EAP build version

We release Early Access Preview (EAP) builds to special channels where Early adopters in that community can try them out and provide feedback. Such builds do not provide any compatibility guarantees (although we do our best to keep them reasonably compatible with distributions and with each other). Such builds are also expected to be of much lower quality than releases. Beta releases also fall into this category.

Important: All binaries compiled with EAP for 1.x (e.g. 1.0-eAP-x) will be rejected by the compiler distribution version. We don’t want any code compiled in the pre-release to survive the stable release. This does not involve patched versions of eaps (such as 1.1.3-EAP-X) that produce builds with stable ABI.

Compatibility mode

When a large team moves to a new release, there may be an “inconsistent state” at some point when some developers have updated and others have not. To prevent the former from writing and committing code that others might not be able to compile, we provide the following command-line switches (also available in the IDE and Gradle/Maven) :

• -language-version X.Y— compatibility mode for Kotlin language version X.Y, reporting errors for all subsequent language features
• -api-version X.Y— Kotlin API version X.Y compatibility mode that reports errors for all code using new versions of the API from the Kotlin standard library, including compiler-generated code.

Binary compatibility warning

If you use the NV Kotlin compiler and have the OV standard library or OV reflection library in your CLASspath, it may be a sign that your project is misconfigured. To prevent unexpected compile-time or run-time problems, we recommend either updating dependencies to NV or explicitly specifying API version/language version parameters. Otherwise the compiler will detect that something is likely to go wrong and report a warning.

For example, if OV = 1.0 and NV = 1.1, you might observe one of the following warnings:

Runtime JAR files in the classpath have the version 1.0, which is older than the API version 1.1. 
Consider using the runtime of version 1.1, or pass '-api-version 1.0' explicitly to restrict the 
available APIs to the runtime of version 1.0.
Copy the code

This means you are using the Kotlin compiler 1.1 for version 1.0 of the standard library or reflection library. This can be handled in different ways:

• If you plan to use apis from the 1.1 library or language features that rely on those apis, upgrade your dependencies to version 1.1.
• If you want to keep your code compliant with the 1.0 library, you can pass in the reference- API - version 1.0.
• If you just upgraded to Kotlin 1.1 and can’t use the new language features (for example, because some of your teammates may not have upgraded), you can pass in the reference- language - version 1.0, which limits all API and language functionality to 1.0.

Runtime JAR files in the classpath should have the same version. These files were found in the classpath: Kotlin-reflect. Jar (version 1.0) Kotlin-stdlib. jar (version 1.1) Consider providing an Explicit Dependency on Kotlin-reflect 1.1 to prevent strange errors Some Runtime JAR files in the classpath have an incompatible version. Consider removing them from the classpathCopy the code

This means that you have dependencies on different versions of libraries, such as the 1.1 standard library and the 1.0 reflection library. To prevent subtle errors at run time, we recommend that you use the same version of all the Kotlin libraries. In this case, consider adding explicit dependencies to the 1.1 reflection library.

Some JAR files in the classpath have the Kotlin Runtime library bundled into them. 
This may cause difficult to debug problems if there's a different version of the Kotlin Runtime library in the classpath. 
Consider removing these libraries from the classpath
Copy the code

This means that there is a library in the classpath that is not dependent on the Kotlin standard library as a Gradle/Maven dependency, but is distributed in the same component as it (that is, bundled). Such a library can cause problems because it is not considered an instance of the Kotlin standard library by standard build tools, so it is not limited by the dependent version resolution mechanism and you can find multiple versions of the same library in your classpath. Consider contacting the author of such a library and suggest using Gradle/Maven dependencies instead.