Add docs for different metadata versions and proto files

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

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)

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";