feat(core,conference): add ExperimentalSdkApi and annotate Breakouts (#…

…531)

The feature is not complete and it would help consumers to be aware of
that until the API is stable.

sdk-conference/build.gradle.kts

@@ -4,6 +4,7 @@ plugins {
 
 kotlin.sourceSets.all {
     languageSettings.optIn("com.pexip.sdk.core.InternalSdkApi")
+    languageSettings.optIn("com.pexip.sdk.core.ExperimentalSdkApi")
 }
 
 dependencies {

sdk-conference/src/main/kotlin/com/pexip/sdk/conference/Breakout.kt

@@ -15,12 +15,14 @@
  */
 package com.pexip.sdk.conference
 
+import com.pexip.sdk.core.ExperimentalSdkApi
 import com.pexip.sdk.infinity.BreakoutId
 import com.pexip.sdk.infinity.ParticipantId
 
 /**
  * A breakout in a conference.
  */
+@ExperimentalSdkApi
 public interface Breakout {
 
     /**

sdk-conference/src/main/kotlin/com/pexip/sdk/conference/Breakouts.kt

@@ -15,12 +15,14 @@
  */
 package com.pexip.sdk.conference
 
+import com.pexip.sdk.core.ExperimentalSdkApi
 import com.pexip.sdk.infinity.BreakoutId
 import kotlinx.coroutines.flow.StateFlow
 
 /**
  * Handles conference breakouts.
  */
+@ExperimentalSdkApi
 public interface Breakouts {
 
     /**

sdk-conference/src/main/kotlin/com/pexip/sdk/conference/Conference.kt

@@ -15,6 +15,7 @@
  */
 package com.pexip.sdk.conference
 
+import com.pexip.sdk.core.ExperimentalSdkApi
 import com.pexip.sdk.infinity.ServiceType
 import com.pexip.sdk.infinity.VersionId
 import com.pexip.sdk.media.MediaConnection
@@ -47,6 +48,7 @@ public interface Conference {
 
     public val messenger: Messenger
 
+    @ExperimentalSdkApi
     public val breakouts: Breakouts get() = throw NotImplementedError()
 
     public val serviceType: ServiceType

sdk-core/api/sdk-core.api

@@ -1,3 +1,6 @@
+public abstract interface annotation class com/pexip/sdk/core/ExperimentalSdkApi : java/lang/annotation/Annotation {
+}
+
 public abstract interface annotation class com/pexip/sdk/core/InternalSdkApi : java/lang/annotation/Annotation {
 }
 

sdk-core/src/commonMain/kotlin/com/pexip/sdk/core/ExperimentalSdkApi.kt

@@ -0,0 +1,44 @@
+/*
+ * Copyright 2024 Pexip AS
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.pexip.sdk.core
+
+/**
+ * Marks declarations that are **experimental** in SDK API, which means their signatures and
+ * semantics will change between future releases without any warnings and without providing any
+ * migration aids.
+ */
+@Retention(value = AnnotationRetention.BINARY)
+@Target(
+    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,
+)
+@RequiresOptIn(
+    level = RequiresOptIn.Level.ERROR,
+    message = """
+        This is an experimental com.pexip.sdk API. No compatibility guarantees are provided. 
+    """,
+)
+@MustBeDocumented
+public annotation class ExperimentalSdkApi

sdk-core/src/commonMain/kotlin/com/pexip/sdk/core/InternalSdkApi.kt

@@ -35,4 +35,5 @@ package com.pexip.sdk.core
         internal API to com.pexip.sdk issue tracker, so stable API could be provided instead.
     """,
 )
+@MustBeDocumented
 public annotation class InternalSdkApi