diff --git a/compiler/ir/serialization.common/src/KotlinIr.proto b/compiler/ir/serialization.common/src/KotlinIr.proto
index 1111491746b..0439f52d9a5 100644
--- a/compiler/ir/serialization.common/src/KotlinIr.proto
+++ b/compiler/ir/serialization.common/src/KotlinIr.proto
@@ -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;
diff --git a/compiler/util-klib-metadata/src/KlibMetadataProtoBuf.proto b/compiler/util-klib-metadata/src/KlibMetadataProtoBuf.proto
index b40d8c0898a..ffe070d568c 100644
--- a/compiler/util-klib-metadata/src/KlibMetadataProtoBuf.proto
+++ b/compiler/util-klib-metadata/src/KlibMetadataProtoBuf.proto
@@ -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";
 
diff --git a/compiler/util-klib-metadata/src/org/jetbrains/kotlin/library/metadata/KlibDeserializedContainerSource.kt b/compiler/util-klib-metadata/src/org/jetbrains/kotlin/library/metadata/KlibDeserializedContainerSource.kt
index a59fbf8717d..7b32674a714 100644
--- a/compiler/util-klib-metadata/src/org/jetbrains/kotlin/library/metadata/KlibDeserializedContainerSource.kt
+++ b/compiler/util-klib-metadata/src/org/jetbrains/kotlin/library/metadata/KlibDeserializedContainerSource.kt
@@ -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
diff --git a/compiler/util-klib-metadata/src/org/jetbrains/kotlin/library/metadata/KlibMetadataMetadataVersion.kt b/compiler/util-klib-metadata/src/org/jetbrains/kotlin/library/metadata/KlibMetadataMetadataVersion.kt
index bfe37dbe115..d66176f269e 100644
--- a/compiler/util-klib-metadata/src/org/jetbrains/kotlin/library/metadata/KlibMetadataMetadataVersion.kt
+++ b/compiler/util-klib-metadata/src/org/jetbrains/kotlin/library/metadata/KlibMetadataMetadataVersion.kt
@@ -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)
diff --git a/compiler/util-klib/KotlinAbiVersionBumpHistory.md b/compiler/util-klib/KotlinAbiVersionBumpHistory.md
new file mode 100644
index 00000000000..24c4724166a
--- /dev/null
+++ b/compiler/util-klib/KotlinAbiVersionBumpHistory.md
@@ -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.
+
+- ...
diff --git a/compiler/util-klib/src/org/jetbrains/kotlin/library/KotlinAbiVersion.kt b/compiler/util-klib/src/org/jetbrains/kotlin/library/KotlinAbiVersion.kt
index 87ad2e077d7..9211c3b6d73 100644
--- a/compiler/util-klib/src/org/jetbrains/kotlin/library/KotlinAbiVersion.kt
+++ b/compiler/util-klib/src/org/jetbrains/kotlin/library/KotlinAbiVersion.kt
@@ -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)
     }
 }
diff --git a/compiler/util-klib/src/org/jetbrains/kotlin/library/KotlinLibrary.kt b/compiler/util-klib/src/org/jetbrains/kotlin/library/KotlinLibrary.kt
index 085d5af7de8..b771347c5f7 100644
--- a/compiler/util-klib/src/org/jetbrains/kotlin/library/KotlinLibrary.kt
+++ b/compiler/util-klib/src/org/jetbrains/kotlin/library/KotlinLibrary.kt
@@ -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"
diff --git a/compiler/util-klib/src/org/jetbrains/kotlin/library/SearchPathResolver.kt b/compiler/util-klib/src/org/jetbrains/kotlin/library/SearchPathResolver.kt
index 2cc50842780..ee08ed86383 100644
--- a/compiler/util-klib/src/org/jetbrains/kotlin/library/SearchPathResolver.kt
+++ b/compiler/util-klib/src/org/jetbrains/kotlin/library/SearchPathResolver.kt
@@ -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
diff --git a/core/metadata.jvm/src/org/jetbrains/kotlin/metadata/jvm/deserialization/JvmMetadataVersion.kt b/core/metadata.jvm/src/org/jetbrains/kotlin/metadata/jvm/deserialization/JvmMetadataVersion.kt
index 2e6a946610f..23f58260739 100644
--- a/core/metadata.jvm/src/org/jetbrains/kotlin/metadata/jvm/deserialization/JvmMetadataVersion.kt
+++ b/core/metadata.jvm/src/org/jetbrains/kotlin/metadata/jvm/deserialization/JvmMetadataVersion.kt
@@ -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)
 
diff --git a/core/metadata/src/builtins.proto b/core/metadata/src/builtins.proto
index 2b0730254d0..8ae24d76ffc 100644
--- a/core/metadata/src/builtins.proto
+++ b/core/metadata/src/builtins.proto
@@ -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;
 
diff --git a/core/metadata/src/metadata.proto b/core/metadata/src/metadata.proto
index cf63f7ccb45..6299a36badb 100644
--- a/core/metadata/src/metadata.proto
+++ b/core/metadata/src/metadata.proto
@@ -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;
 
diff --git a/core/metadata/src/org/jetbrains/kotlin/metadata/builtins/BuiltInsBinaryVersion.kt b/core/metadata/src/org/jetbrains/kotlin/metadata/builtins/BuiltInsBinaryVersion.kt
index 709d31cb479..2426f97f11c 100644
--- a/core/metadata/src/org/jetbrains/kotlin/metadata/builtins/BuiltInsBinaryVersion.kt
+++ b/core/metadata/src/org/jetbrains/kotlin/metadata/builtins/BuiltInsBinaryVersion.kt
@@ -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 =
diff --git a/js/js.config/src/org/jetbrains/kotlin/utils/KotlinJavascriptMetadataUtils.kt b/js/js.config/src/org/jetbrains/kotlin/utils/KotlinJavascriptMetadataUtils.kt
index ad1271b8845..fcd4c5c2ac7 100644
--- a/js/js.config/src/org/jetbrains/kotlin/utils/KotlinJavascriptMetadataUtils.kt
+++ b/js/js.config/src/org/jetbrains/kotlin/utils/KotlinJavascriptMetadataUtils.kt
@@ -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)
diff --git a/js/js.serializer/src/js.proto b/js/js.serializer/src/js.proto
index 935e1b5f6bc..6557c0ab8bc 100644
--- a/js/js.serializer/src/js.proto
+++ b/js/js.serializer/src/js.proto
@@ -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";