Introduce RequiresOptIn and OptIn annotations

RequiresOptIn should be used now instead of Experimental, OptIn instead
of UseExperimental. See https://github.com/Kotlin/KEEP/pull/201.

This change adds the new declarations only to the stdlib, and supports
them in the compiler. Because of the way compiler loads annotations, we
need to bootstrap it first before deprecating the old annotations and
updating tests.

 #KT-34647 Fixed

libraries/stdlib/src/kotlin/annotations/ExperimentalStdlibApi.kt

@@ -15,6 +15,7 @@ import kotlin.annotation.AnnotationTarget.*
  * or by using the compiler argument `-Xuse-experimental=kotlin.ExperimentalStdlibApi`.
  */
 @Experimental(level = Experimental.Level.ERROR)
+@RequiresOptIn(level = RequiresOptIn.Level.ERROR)
 @Retention(AnnotationRetention.BINARY)
 @Target(
     CLASS,

libraries/stdlib/src/kotlin/annotations/Multiplatform.kt

@@ -17,6 +17,7 @@ import kotlin.internal.RequireKotlinVersionKind
  * or by using the compiler argument `-Xuse-experimental=kotlin.ExperimentalMultiplatform`.
  */
 @Experimental
+@RequiresOptIn
 @MustBeDocumented
 @Target(
     CLASS,

libraries/stdlib/src/kotlin/annotations/OptIn.kt

@@ -0,0 +1,55 @@
+/*
+ * Copyright 2010-2018 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
+
+import kotlin.annotation.AnnotationRetention.BINARY
+import kotlin.annotation.AnnotationRetention.SOURCE
+import kotlin.annotation.AnnotationTarget.*
+import kotlin.internal.RequireKotlin
+import kotlin.internal.RequireKotlinVersionKind
+import kotlin.reflect.KClass
+
+/**
+ * Signals that the annotated annotation class is a marker of an API that requires an explicit opt-in.
+ *
+ * Call sites of any declaration annotated with that marker should opt-in to the API either by using [OptIn],
+ * or by being annotated with that marker themselves, effectively causing further propagation of the opt-in requirement.
+ *
+ * This class requires opt-in itself and can only be used with the compiler argument `-Xopt-in=kotlin.RequiresOptIn`.
+ */
+@Target(ANNOTATION_CLASS)
+@Retention(BINARY)
+@SinceKotlin("1.3")
+@RequireKotlin("1.3.70", versionKind = RequireKotlinVersionKind.COMPILER_VERSION)
+public annotation class RequiresOptIn(val level: Level = Level.ERROR) {
+    /**
+     * Severity of the diagnostic that should be reported on usages which did not explicitly opted into
+     * the API either by using [OptIn] or by being annotated with the corresponding marker annotation.
+     */
+    public enum class Level {
+        /** Specifies that a warning should be reported on incorrect usages of this API. */
+        WARNING,
+
+        /** Specifies that an error should be reported on incorrect usages of this API. */
+        ERROR,
+    }
+}
+
+/**
+ * Allows to use the API denoted by the given markers in the annotated file, declaration, or expression.
+ * If a declaration is annotated with [OptIn], its usages are **not** required to opt-in to that API.
+ *
+ * This class requires opt-in itself and can only be used with the compiler argument `-Xopt-in=kotlin.RequiresOptIn`.
+ */
+@Target(
+    CLASS, PROPERTY, LOCAL_VARIABLE, VALUE_PARAMETER, CONSTRUCTOR, FUNCTION, PROPERTY_GETTER, PROPERTY_SETTER, EXPRESSION, FILE, TYPEALIAS
+)
+@Retention(SOURCE)
+@SinceKotlin("1.3")
+@RequireKotlin("1.3.70", versionKind = RequireKotlinVersionKind.COMPILER_VERSION)
+public annotation class OptIn(
+    vararg val markerClass: KClass<out Annotation>
+)

libraries/stdlib/src/kotlin/contracts/ContractBuilder.kt

@@ -19,6 +19,7 @@ import kotlin.internal.InlineOnly
 @Retention(AnnotationRetention.BINARY)
 @SinceKotlin("1.3")
 @Experimental
+@RequiresOptIn
 @MustBeDocumented
 public annotation class ExperimentalContracts
 
@@ -147,4 +148,4 @@ public enum class InvocationKind {
 @InlineOnly
 @SinceKotlin("1.3")
 @Suppress("UNUSED_PARAMETER")
-public inline fun contract(builder: ContractBuilder.() -> Unit) { }
+public inline fun contract(builder: ContractBuilder.() -> Unit) { }

libraries/stdlib/src/kotlin/experimental/inferenceMarker.kt

@@ -13,6 +13,7 @@ package kotlin.experimental
  * or by using the compiler argument `-Xuse-experimental=kotlin.experimental.ExperimentalTypeInference`.
  */
 @Experimental(level = Experimental.Level.ERROR)
+@RequiresOptIn(level = RequiresOptIn.Level.ERROR)
 @MustBeDocumented
 @Retention(AnnotationRetention.BINARY)
 @Target(AnnotationTarget.ANNOTATION_CLASS)

libraries/stdlib/src/kotlin/time/ExperimentalTime.kt

@@ -19,6 +19,7 @@ import kotlin.annotation.AnnotationTarget.*
  * or by using the compiler argument `-Xuse-experimental=kotlin.time.ExperimentalTime`.
  */
 @Experimental(level = Experimental.Level.ERROR)
+@RequiresOptIn(level = RequiresOptIn.Level.ERROR)
 @MustBeDocumented
 @Retention(AnnotationRetention.BINARY)
 @Target(
@@ -35,4 +36,4 @@ import kotlin.annotation.AnnotationTarget.*
     TYPEALIAS
 )
 @SinceKotlin("1.3")
-public annotation class ExperimentalTime
+public annotation class ExperimentalTime