feat!: mark client-side bindings as experimental (#1211)

Fixes #1207.
typesafegithub · Dec 26, 2023 · 1b84a3e · 1b84a3e
1 parent 9127914
commit 1b84a3e
Show file tree

Hide file tree

Showing 8 changed files with 32 additions and 0 deletions.
diff --git a/action-binding-generator/api/action-binding-generator.api b/action-binding-generator/api/action-binding-generator.api
@@ -192,3 +192,6 @@ public final class io/github/typesafegithub/workflows/actionbindinggenerator/Typ
 	public static fun values ()[Lio/github/typesafegithub/workflows/actionbindinggenerator/TypingActualSource;
 }
 
+public abstract interface annotation class io/github/typesafegithub/workflows/actionbindinggenerator/annotations/ExperimentalClientSideBindings : java/lang/annotation/Annotation {
+}
+
diff --git a/...github/typesafegithub/workflows/actionbindinggenerator/GenerateActionBindingsCliHelper.kt b/...github/typesafegithub/workflows/actionbindinggenerator/GenerateActionBindingsCliHelper.kt
@@ -1,5 +1,6 @@
 package io.github.typesafegithub.workflows.actionbindinggenerator
 
+import io.github.typesafegithub.workflows.actionbindinggenerator.annotations.ExperimentalClientSideBindings
 import io.github.typesafegithub.workflows.shared.internal.findGitRoot
 import java.nio.file.Path
 import kotlin.io.path.div
@@ -13,6 +14,7 @@ import kotlin.io.path.div
  * @param sourceFile Path to the script where this function is called from. Typically a result of an expression like
  * [__FILE__.toPath()].
  */
+@ExperimentalClientSideBindings
 public fun generateActionBindings(
     args: Array<String>,
     sourceFile: Path,

diff --git a/...r/src/main/kotlin/io/github/typesafegithub/workflows/actionbindinggenerator/Generation.kt b/...r/src/main/kotlin/io/github/typesafegithub/workflows/actionbindinggenerator/Generation.kt
@@ -143,6 +143,11 @@ private fun generateActionClass(
 ): TypeSpec {
     return TypeSpec.classBuilder(className)
         .addModifiers(KModifier.DATA)
+        .apply {
+            if (generateForScript) {
+                addExperimentalAnnotation()
+            }
+        }
         .addKdoc(actionKdoc(metadata, coords))
         .addMaybeDeprecated(coords)
         .inheritsFromRegularAction(coords, metadata, className, generateForScript = generateForScript)
@@ -156,6 +161,13 @@ private fun generateActionClass(
         .build()
 }
 
+private fun TypeSpec.Builder.addExperimentalAnnotation() {
+    addAnnotation(
+        AnnotationSpec.builder(ClassName("io.github.typesafegithub.workflows.annotations", "ExperimentalClientSideBindings"))
+            .build(),
+    )
+}
+
 private fun TypeSpec.Builder.addCustomTypes(
     typings: Map<String, Typing>,
     coords: ActionCoords,

diff --git a/...safegithub/workflows/actionbindinggenerator/annotations/ExperimentalClientSideBindings.kt b/...safegithub/workflows/actionbindinggenerator/annotations/ExperimentalClientSideBindings.kt
@@ -0,0 +1,4 @@
+package io.github.typesafegithub.workflows.actionbindinggenerator.annotations
+
+@RequiresOptIn
+public annotation class ExperimentalClientSideBindings
diff --git a/...ub/typesafegithub/workflows/actionbindinggenerator/GenerateActionBindingsCliHelperTest.kt b/...ub/typesafegithub/workflows/actionbindinggenerator/GenerateActionBindingsCliHelperTest.kt
@@ -1,9 +1,11 @@
 package io.github.typesafegithub.workflows.actionbindinggenerator
 
+import io.github.typesafegithub.workflows.actionbindinggenerator.annotations.ExperimentalClientSideBindings
 import io.kotest.core.spec.style.FunSpec
 import io.kotest.engine.spec.tempdir
 import io.kotest.matchers.shouldBe
 
+@OptIn(ExperimentalClientSideBindings::class)
 class GenerateActionBindingsCliHelperTest : FunSpec({
     test("${::generateActionBindings.name} - smoke test") {
         // given

diff --git a/...c/test/kotlin/io/github/typesafegithub/workflows/actionbindinggenerator/GenerationTest.kt b/...c/test/kotlin/io/github/typesafegithub/workflows/actionbindinggenerator/GenerationTest.kt
@@ -436,6 +436,7 @@ class GenerationTest : FunSpec({
                 "DEPRECATION",
             )
 
+            import io.github.typesafegithub.workflows.annotations.ExperimentalClientSideBindings
             import io.github.typesafegithub.workflows.domain.actions.Action
             import io.github.typesafegithub.workflows.domain.actions.RegularAction
             import java.util.LinkedHashMap
@@ -455,6 +456,7 @@ class GenerationTest : FunSpec({
              *
              * [Action on GitHub](https://github.com/john-smith/action-for-script)
              */
+            @ExperimentalClientSideBindings
             public data class ActionForScript private constructor(
                 /**
                  * Short description

diff --git a/github-workflows-kt/api/github-workflows-kt.api b/github-workflows-kt/api/github-workflows-kt.api
@@ -1,3 +1,6 @@
+public abstract interface annotation class io/github/typesafegithub/workflows/annotations/ExperimentalClientSideBindings : java/lang/annotation/Annotation {
+}
+
 public abstract class io/github/typesafegithub/workflows/domain/AbstractResult {
 	public final fun eq (Lio/github/typesafegithub/workflows/domain/AbstractResult$Status;)Ljava/lang/String;
 	public final fun neq (Lio/github/typesafegithub/workflows/domain/AbstractResult$Status;)Ljava/lang/String;

diff --git a/...n/kotlin/io/github/typesafegithub/workflows/annotations/ExperimentalClientSideBindings.kt b/...n/kotlin/io/github/typesafegithub/workflows/annotations/ExperimentalClientSideBindings.kt
@@ -0,0 +1,4 @@
+package io.github.typesafegithub.workflows.annotations
+
+@RequiresOptIn
+public annotation class ExperimentalClientSideBindings