Add docs for different metadata versions and proto files

Review: https://jetbrains.team/p/kt/reviews/8401 In scope of KT-55082
2023-01-09 10:04:32 +01:00
parent 62b27b4613
commit 44b1cf6c46
14 changed files with 124 additions and 7 deletions
@@ -1,6 +1,8 @@
 syntax = "proto2";
 package org.jetbrains.kotlin.backend.common.serialization.proto;

+// Changes to this proto are tracked by KotlinAbiVersion version. See KotlinAbiVersion KDoc.
+
 option java_multiple_files = true;
 option java_outer_classname = "KotlinIr";
 option optimize_for = LITE_RUNTIME;
@@ -16,6 +16,8 @@

 package org.jetbrains.kotlin.library.metadata;

+// Changes to this proto are tracked by KlibMetadataVersion version. See KlibMetadataVersion KDoc.
+
 import "core/metadata/src/metadata.proto";
 import "core/metadata/src/ext_options.proto";

@@ -34,7 +34,7 @@ class KlibDeserializedContainerSource private constructor(
    )

    override val incompatibility: IncompatibleVersionErrorData<*>?
-        get() = null
+        get() = null // TODO KT-55808

    override val abiStability: DeserializedContainerAbiStability
        get() = DeserializedContainerAbiStability.STABLE
@@ -9,6 +9,19 @@ import org.jetbrains.kotlin.library.KLIB_PROPERTY_METADATA_VERSION
 import org.jetbrains.kotlin.library.KotlinLibrary
 import org.jetbrains.kotlin.metadata.deserialization.BinaryVersion

+/**
+ * The version for `KlibMetadataProtoBuf.proto`. This version also includes the version of the core protobuf messages (`metadata.proto`).
+ *
+ * This version must be bumped when:
+ * - Incompatible changes are made in `KlibMetadataProtoBuf.proto`
+ * - Incompatible changes are made in `metadata.proto`
+ * - Incompatible changes are made in Klib metadata serialization/deserialization logic
+ *
+ * The version bump must obey [org.jetbrains.kotlin.metadata.deserialization.BinaryVersion] rules (See `BinaryVersion` KDoc).
+ *
+ * Known bugs: [KlibMetadataVersion] isn't currently checked for klibs [KT-55808](https://youtrack.jetbrains.com/issue/KT-55808)
+ * [KT-56062](https://youtrack.jetbrains.com/issue/KT-56062).
+ */
 class KlibMetadataVersion(vararg numbers: Int) : BinaryVersion(*numbers) {

    override fun isCompatibleWithCurrentCompilerVersion(): Boolean = isCompatibleTo(INSTANCE)
@@ -0,0 +1,43 @@
+# KotlinAbiVersion bump history
+
+- Incompatible change in KotlinIr.proto  
+  `1b6a43ba69a 2022-07-21 Vsevolod Tolstopyatov Update IR serialization to reflect changes in IrSyntheticBodyKind for enum entries`  
+  but we can skip abi version bump because we check some other version in different place KT-53620.
+
+- Bump 1.6.0 -> 1.7.0  
+  `76da9df1021 2022-05-26 Pavel Kunyavskiy Bump klib ABI version`
+- The bump is caused by incompatible change in KotlinIr.proto  
+  `d809e260cb1 2021-10-25 Roman Artemev [KLIB] Support `DefinitelyNotNull` type in KLIB`
+
+- Bump 1.5.0 -> 1.6.0  
+  `3403c464fe0 2021-05-26 Roman Artemev [KLIB] Promote library ABI version`
+- The bump is caused by incompatible change in KotlinIr.proto  
+  `6cdac22a23a 2021-05-26 Roman Artemev [IR] Introduce new IdSignatures`
+
+- Bump 1.4.2 -> 1.5.0  
+  `caee17fddb9 2021-04-08 Dmitriy Dolovov [IR] Bump ABI version due to string serialization format change`
+- The bump is caused by string serialization format change in IR  
+  `50326f019b7 2021-03-30 Dmitriy Dolovov [IR] Use the proper encoding for string serialization`
+
+- Bump 1.4.1 -> 1.4.2  
+  `eea5a9102c4 2020-11-06 Alexander Gorshenev Bump klib abi version to 1.4.2 to reflect absence of serialized fake overrides`
+- The bump is caused by stopping serializing overrides. Normally this would be forwards incompatible change and minor version
+  should have been bumped, not patch version. But since the code supported the case of fake overrides absence from the beginning,
+  only patch version was bumped  
+  `cb288d47ea5 2020-11-05 Alexander Gorshenev Don't serialize fake overrides anymore`
+
+- Bump 1.4.0 -> 1.4.1  
+  `d7226f49522 2020-04-10 Dmitriy Dolovov KLIB. Promote KLIB ABI version`
+- The bump is caused by
+  - `101442ad14b 2020-04-03 Dmitriy Dolovov KLIB: Store native targets in manifest`
+  - `1b06256650d 2020-04-03 Dmitriy Dolovov KLIB: Add 'native_targets' manifest property`
+
+- Bump 0.26.0 -> 1.4.0  
+  `b06a3ea5acb 2020-03-06 Alexander Gorshenev Print out abi version as a full triple`
+- There is no clear reasons why the bump was needed. I presume that the author was afraid of version format change. The version
+  was bumped up to 1.4.0 but not to 1.0.0 presumably because of `isVersionRequirementTableWrittenCorrectly` (It checks that
+  version is at least 1.4) but `isVersionRequirementTableWrittenCorrectly` is invoked only for `BinaryVersion` (and presumably
+  only for backend specific metadatas, not for IR) => bump up to 1.0.0 was sufficient. Presumably the author wanted to be extra
+  safe.
+
+- ...
@@ -26,8 +26,20 @@ fun String.parseKotlinAbiVersion(): KotlinAbiVersion {
    }
 }

-// TODO: it would be nice to inherit this one from BinaryVersion,
-// but that requires a module structure refactoring.
+// TODO: consider inheriting this class from BinaryVersion (but that requires a module structure refactoring.)
+//  Advantages: code reuse.
+//  Disadvantages: BinaryVersion is a problematic class, because it doesn't represent any logical entity in the codebase, it's just a
+//  way to reuse common logic for Kotlin versions. But unfortunately, BinaryVersion is used in a lot of API definitions, which makes
+//  code hard to read because it's not obvious which subclasses are supposed to be passed into a particular API.
+/**
+ * The version of the Kotlin IR.
+ *
+ * This version must be bumped when:
+ * - Incompatible changes are made in `KotlinIr.proto`
+ * - Incompatible changes are made in serialization/deserialization logic
+ *
+ * The version bump must obey [org.jetbrains.kotlin.metadata.deserialization.BinaryVersion] rules (See `BinaryVersion` KDoc)
+ */
 data class KotlinAbiVersion(val major: Int, val minor: Int, val patch: Int) {
    // For 1.4 compiler we switched klib abi_version to a triple,
    // but we don't break if we still encounter a single digit from 1.3.
@@ -60,6 +72,9 @@ data class KotlinAbiVersion(val major: Int, val minor: Int, val patch: Int) {
    override fun toString() = "$major.$minor.$patch"

    companion object {
+        /**
+         * See: [KotlinAbiVersion bump history](compiler/util-klib/KotlinAbiVersionBumpHistory.md)
+         */
        val CURRENT = KotlinAbiVersion(1, 7, 0)
    }
 }
@@ -4,11 +4,18 @@ import org.jetbrains.kotlin.konan.file.File
 import org.jetbrains.kotlin.konan.properties.Properties
 import org.jetbrains.kotlin.konan.properties.propertyList

+/**
+ * [org.jetbrains.kotlin.library.KotlinAbiVersion]
+ */
 const val KLIB_PROPERTY_ABI_VERSION = "abi_version"
 const val KLIB_PROPERTY_COMPILER_VERSION = "compiler_version"
+
+/**
+ * [org.jetbrains.kotlin.library.metadata.KlibMetadataVersion]
+ */
+const val KLIB_PROPERTY_METADATA_VERSION = "metadata_version"
 const val KLIB_PROPERTY_DEPENDENCY_VERSION = "dependency_version"
 const val KLIB_PROPERTY_LIBRARY_VERSION = "library_version"
-const val KLIB_PROPERTY_METADATA_VERSION = "metadata_version"
 const val KLIB_PROPERTY_UNIQUE_NAME = "unique_name"
 const val KLIB_PROPERTY_SHORT_NAME = "short_name"
 const val KLIB_PROPERTY_DEPENDS = "depends"
@@ -237,6 +237,9 @@ abstract class KotlinLibraryProperResolverWithAttributes<L : KotlinLibrary>(
        val candidateAbiVersion = candidate.versions.abiVersion
        val candidateLibraryVersion = candidate.versions.libraryVersion

+        // Rejecting a library at this stage has disadvantages - the diagnostics are not-understandable.
+        // Please, don't add checks for other versions here. For example, check for the metadata version should be
+        // implemented in KlibDeserializedContainerSource.incompatibility
        if (candidateAbiVersion?.isCompatible() != true) {
            logger.warning("skipping $candidatePath. Incompatible abi version. The current default is '${KotlinAbiVersion.CURRENT}', found '${candidateAbiVersion}'. The library produced by ${candidateCompilerVersion} compiler")
            return false
@@ -10,7 +10,10 @@ import org.jetbrains.kotlin.metadata.deserialization.BinaryVersion
 /**
 * The version of the metadata serialized by the compiler and deserialized by the compiler and reflection.
 * This version includes the version of the core protobuf messages (metadata.proto) as well as JVM extensions (jvm_metadata.proto).
- */
+ *
+ * Please note that [JvmMetadataVersion] is different compared to other [BinaryVersion]s. The version bump **DOESN'T** obey [BinaryVersion]
+ * rules. Starting from Kotlin 1.4, [JvmMetadataVersion] major and minor tokens always match the compilers corresponding version tokens.
+ **/
 class JvmMetadataVersion(versionArray: IntArray, val isStrictSemantics: Boolean) : BinaryVersion(*versionArray) {
    constructor(vararg numbers: Int) : this(numbers, isStrictSemantics = false)

@@ -18,6 +18,8 @@ package org.jetbrains.kotlin.metadata.builtins;

 import "core/metadata/src/metadata.proto";

+// Changes to this proto are tracked by BuiltInsBinaryVersion version. See BuiltInsBinaryVersion KDoc.
+
 option java_outer_classname = "BuiltInsProtoBuf";
 option optimize_for = LITE_RUNTIME;

@@ -18,6 +18,10 @@ package org.jetbrains.kotlin.metadata;

 import "core/metadata/src/ext_options.proto";

+// Changes to this proto are tracked by versions of proto files that include `import metadata.proto`.
+// Namely BuiltInsBinaryVersion, JvmMetadataVersion, JsMetadataVersion, KlibMetadataVersion, and probably something else.
+// See their KDocs.
+
 option java_outer_classname = "ProtoBuf";
 option optimize_for = LITE_RUNTIME;

@@ -10,8 +10,15 @@ import java.io.DataInputStream
 import java.io.InputStream

 /**
- * The version of the format in which the .kotlin_builtins file is stored. This version also includes the version
- * of the core protobuf messages (metadata.proto).
+ * The version of the format in which the `.kotlin_builtins` (`builtins.proto`) file is stored. This version also includes the version
+ * of the core protobuf messages (`metadata.proto`).
+ *
+ * This version must be bumped when:
+ * - Incompatible changes are made in `builtins.proto`
+ * - Incompatible changes are made in `metadata.proto`
+ * - Incompatible changes are made in builtins serialization/deserialization logic
+ *
+ * The version bump must obey [org.jetbrains.kotlin.metadata.deserialization.BinaryVersion] rules (See `BinaryVersion` KDoc).
 */
 class BuiltInsBinaryVersion(vararg numbers: Int) : BinaryVersion(*numbers) {
    override fun isCompatibleWithCurrentCompilerVersion(): Boolean =
@@ -13,6 +13,20 @@ import java.util.*

 class KotlinJavascriptMetadata(val version: JsMetadataVersion, val moduleName: String, val body: ByteArray)

+/**
+ * The version of the format in which the `js.proto` is stored. This version also includes the version of the core protobuf messages
+ * (`metadata.proto`).
+ *
+ * This version must be bumped when:
+ * - Incompatible changes are made in `js.proto`
+ * - Incompatible changes are made in `metadata.proto`
+ * - Incompatible changes are made in JS metadata serialization/deserialization logic
+ *
+ * This version must **NOT** be bumped when:
+ * - Incompatible changes are made in `js-ast.proto`. `js-ast.proto` is and internal format used for incremental compilation caches
+ *
+ * The version bump must obey [org.jetbrains.kotlin.metadata.deserialization.BinaryVersion] rules (See `BinaryVersion` KDoc).
+ */
 class JsMetadataVersion(vararg numbers: Int) : BinaryVersion(*numbers) {
    override fun isCompatibleWithCurrentCompilerVersion(): Boolean =
        this.isCompatibleTo(INSTANCE)
@@ -16,6 +16,8 @@

 package org.jetbrains.kotlin.metadata.js;

+// Whenever you change this proto in an incompatible way, don't forget to bump JsMetadataVersion
+
 import "core/metadata/src/metadata.proto";

 option java_outer_classname = "JsProtoBuf";