From 5417fde99a1f811dff114b543e0a483cd93e0044 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ivan=20=E2=80=9CCLOVIS=E2=80=9D=20Canet?=
 <ivan.canet@gmail.com>
Date: Sat, 9 Aug 2025 12:50:13 +0200
Subject: [PATCH] feat(suite): Added the @ExperimentalPreparedApi annotation

This annotation allows us to release features that are not completely stable.
---
 suite/src/commonMain/kotlin/SuiteDsl.kt       |  4 +++
 .../annotations/ExperimentalPreparedApi.kt    | 26 +++++++++++++++++++
 .../kotlin/annotations/TestEntrypoint.kt      |  3 ++-
 3 files changed, 32 insertions(+), 1 deletion(-)
 create mode 100644 suite/src/commonMain/kotlin/annotations/ExperimentalPreparedApi.kt

diff --git a/suite/src/commonMain/kotlin/SuiteDsl.kt b/suite/src/commonMain/kotlin/SuiteDsl.kt
index c584a73..2ff2b12 100644
--- a/suite/src/commonMain/kotlin/SuiteDsl.kt
+++ b/suite/src/commonMain/kotlin/SuiteDsl.kt
@@ -16,6 +16,7 @@
 
 package opensavvy.prepared.suite
 
+import opensavvy.prepared.suite.annotations.ExperimentalPreparedApi
 import opensavvy.prepared.suite.annotations.TestEntrypoint
 import opensavvy.prepared.suite.config.Context
 import opensavvy.prepared.suite.config.TestConfig
@@ -83,6 +84,7 @@ interface SuiteDsl : PreparedDsl {
 	 *
 	 * To learn more about the available configuration options, see the subtypes of [TestConfig.Element].
 	 */
+	@OptIn(ExperimentalPreparedApi::class)
 	@PreparedDslMarker
 	@TestEntrypoint
 	fun suite(
@@ -120,6 +122,7 @@ interface SuiteDsl : PreparedDsl {
 	 *
 	 * To learn more about the available configuration options, see the subtypes of [TestConfig.Element].
 	 */
+	@OptIn(ExperimentalPreparedApi::class)
 	@PreparedDslMarker
 	@TestEntrypoint
 	fun test(
@@ -128,6 +131,7 @@ interface SuiteDsl : PreparedDsl {
 		block: suspend TestDsl.() -> Unit,
 	)
 
+	@OptIn(ExperimentalPreparedApi::class)
 	@Deprecated(
 		"Prefer injecting the coroutine context using the `Context` test configuration.",
 		ReplaceWith("test(name, config + Context(context), block)", "opensavvy.prepared.suite.config.*"),
diff --git a/suite/src/commonMain/kotlin/annotations/ExperimentalPreparedApi.kt b/suite/src/commonMain/kotlin/annotations/ExperimentalPreparedApi.kt
new file mode 100644
index 0000000..172b672
--- /dev/null
+++ b/suite/src/commonMain/kotlin/annotations/ExperimentalPreparedApi.kt
@@ -0,0 +1,26 @@
+/*
+ * Copyright (c) 2025, OpenSavvy and contributors.
+ *
+ * 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 opensavvy.prepared.suite.annotations
+
+@RequiresOptIn("This is part of an experimental API of the Prepared framework. It could change or be removed without warnings.")
+annotation class ExperimentalPreparedApi(
+	/**
+	 * URL to get more information about the experimental status of this specific API.
+	 */
+	@Suppress("unused")
+	val trackingUrl: String,
+)
diff --git a/suite/src/commonMain/kotlin/annotations/TestEntrypoint.kt b/suite/src/commonMain/kotlin/annotations/TestEntrypoint.kt
index 36fe825..69a732b 100644
--- a/suite/src/commonMain/kotlin/annotations/TestEntrypoint.kt
+++ b/suite/src/commonMain/kotlin/annotations/TestEntrypoint.kt
@@ -27,5 +27,6 @@ package opensavvy.prepared.suite.annotations
  * and no thrown exceptions means a test success.
  */
 @Target(AnnotationTarget.FUNCTION)
-@Retention(AnnotationRetention.SOURCE)
+@Retention(AnnotationRetention.BINARY)
+@ExperimentalPreparedApi("https://gitlab.com/opensavvy/groundwork/prepared/-/issues/86")
 annotation class TestEntrypoint
-- 
2.51.2