Add docs for different metadata versions and proto files

Review: https://jetbrains.team/p/kt/reviews/8401
In scope of KT-55082

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;
 

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;
 

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 =