Introduce @ExperimentalEncodingApi for binary-to-text encoding API

libraries/stdlib/api/js-v1/kotlin.io.encoding.kt

@@ -23,3 +23,12 @@ public open class Base64 {
         public final val UrlSafe: kotlin.io.encoding.Base64 { get; }
     }
 }
+
+@kotlin.RequiresOptIn(level = Level.ERROR)
+@kotlin.annotation.Retention(value = AnnotationRetention.BINARY)
+@kotlin.annotation.Target(allowedTargets = {AnnotationTarget.CLASS, AnnotationTarget.ANNOTATION_CLASS, AnnotationTarget.PROPERTY, AnnotationTarget.FIELD, AnnotationTarget.LOCAL_VARIABLE, AnnotationTarget.VALUE_PARAMETER, AnnotationTarget.CONSTRUCTOR, AnnotationTarget.FUNCTION, AnnotationTarget.PROPERTY_GETTER, AnnotationTarget.PROPERTY_SETTER, AnnotationTarget.TYPEALIAS})
+@kotlin.annotation.MustBeDocumented
+@kotlin.SinceKotlin(version = "1.8")
+public final annotation class ExperimentalEncodingApi : kotlin.Annotation {
+    public constructor ExperimentalEncodingApi()
+}

libraries/stdlib/api/js/kotlin.io.encoding.kt

@@ -23,3 +23,12 @@ public open class Base64 {
         public final val UrlSafe: kotlin.io.encoding.Base64 { get; }
     }
 }
+
+@kotlin.RequiresOptIn(level = Level.ERROR)
+@kotlin.annotation.Retention(value = AnnotationRetention.BINARY)
+@kotlin.annotation.Target(allowedTargets = {AnnotationTarget.CLASS, AnnotationTarget.ANNOTATION_CLASS, AnnotationTarget.PROPERTY, AnnotationTarget.FIELD, AnnotationTarget.LOCAL_VARIABLE, AnnotationTarget.VALUE_PARAMETER, AnnotationTarget.CONSTRUCTOR, AnnotationTarget.FUNCTION, AnnotationTarget.PROPERTY_GETTER, AnnotationTarget.PROPERTY_SETTER, AnnotationTarget.TYPEALIAS})
+@kotlin.annotation.MustBeDocumented
+@kotlin.SinceKotlin(version = "1.8")
+public final annotation class ExperimentalEncodingApi : kotlin.Annotation {
+    public constructor ExperimentalEncodingApi()
+}

libraries/stdlib/src/kotlin/io/encoding/ExperimentalEncodingApi.kt

@@ -0,0 +1,37 @@
+/*
+ * Copyright 2010-2023 JetBrains s.r.o. and Kotlin Programming Language contributors.
+ * Use of this source code is governed by the Apache 2.0 license that can be found in the license/LICENSE.txt file.
+ */
+
+package kotlin.io.encoding
+
+import kotlin.annotation.AnnotationTarget.*
+
+/**
+ * This annotation marks the experimental API for encoding and decoding between binary data and printable ASCII character sequences.
+ *
+ * > Beware using the annotated API especially if you're developing a library, since your library might become binary incompatible
+ * with the future versions of the standard library.
+ *
+ * Any usage of a declaration annotated with `@ExperimentalEncodingApi` must be accepted either by
+ * annotating that usage with the [OptIn] annotation, e.g. `@OptIn(ExperimentalEncodingApi::class)`,
+ * or by using the compiler argument `-opt-in=kotlin.io.encoding.ExperimentalEncodingApi`.
+ */
+@RequiresOptIn(level = RequiresOptIn.Level.ERROR)
+@Retention(AnnotationRetention.BINARY)
+@Target(
+    CLASS,
+    ANNOTATION_CLASS,
+    PROPERTY,
+    FIELD,
+    LOCAL_VARIABLE,
+    VALUE_PARAMETER,
+    CONSTRUCTOR,
+    FUNCTION,
+    PROPERTY_GETTER,
+    PROPERTY_SETTER,
+    TYPEALIAS
+)
+@MustBeDocumented
+@SinceKotlin("1.8")
+public annotation class ExperimentalEncodingApi

libraries/tools/binary-compatibility-validator/reference-public-api/kotlin-stdlib-runtime-merged.txt

@@ -3294,6 +3294,9 @@ public final class kotlin/io/encoding/Base64$Default : kotlin/io/encoding/Base64
 	public final fun getUrlSafe ()Lkotlin/io/encoding/Base64;
 }
 
+public abstract interface annotation class kotlin/io/encoding/ExperimentalEncodingApi : java/lang/annotation/Annotation {
+}
+
 public final class kotlin/io/encoding/StreamEncodingKt {
 	public static final fun decodingWith (Ljava/io/InputStream;Lkotlin/io/encoding/Base64;)Ljava/io/InputStream;
 	public static final fun encodingWith (Ljava/io/OutputStream;Lkotlin/io/encoding/Base64;)Ljava/io/OutputStream;