From 5a6f03c1b231e7c863a3918e119c696cd59720bc Mon Sep 17 00:00:00 2001
From: Clement Escoffier <clement.escoffier@gmail.com>
Date: Mon, 7 Oct 2024 11:23:14 +0200
Subject: [PATCH] Introduce an annotation to mark a feature as tech preview

Annotated elements are feature-complete, but have known limitations, need bake-time or have rough angles. The API is more stable than with @Experimental. Tech preview API can still be changed, but changes will be communicated.
---
 .../common/annotation/Experimental.java       |  2 ++
 .../common/annotation/TechPreview.java        | 31 +++++++++++++++++++
 2 files changed, 33 insertions(+)
 create mode 100644 annotation/src/main/java/io/smallrye/common/annotation/TechPreview.java

diff --git a/annotation/src/main/java/io/smallrye/common/annotation/Experimental.java b/annotation/src/main/java/io/smallrye/common/annotation/Experimental.java
index 70894e53..111054fe 100644
--- a/annotation/src/main/java/io/smallrye/common/annotation/Experimental.java
+++ b/annotation/src/main/java/io/smallrye/common/annotation/Experimental.java
@@ -9,6 +9,8 @@
 
 /**
  * Annotation that specifies that an element is experimental and may change without notice.
+ *
+ * @see TechPreview
  */
 @Inherited
 @Documented
diff --git a/annotation/src/main/java/io/smallrye/common/annotation/TechPreview.java b/annotation/src/main/java/io/smallrye/common/annotation/TechPreview.java
new file mode 100644
index 00000000..de8c1e76
--- /dev/null
+++ b/annotation/src/main/java/io/smallrye/common/annotation/TechPreview.java
@@ -0,0 +1,31 @@
+package io.smallrye.common.annotation;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Inherited;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Annotation that specifies that an element is tech preview and may change in the future.
+ * <p>
+ * Annotated elements are feature-complete, but have known limitations, need bake-time or
+ * have rough angles. The API is more stable than with {@link Experimental}.
+ * <p>
+ * Tech preview API can still be changed, but changes will be communicated.
+ *
+ * @see Experimental
+ */
+@Inherited
+@Documented
+@Retention(RetentionPolicy.RUNTIME)
+@Target({ ElementType.METHOD, ElementType.TYPE, ElementType.FIELD, ElementType.PACKAGE })
+public @interface TechPreview {
+    /**
+     * Describes why the annotated element is in tech preview.
+     *
+     * @return the tech preview description.
+     */
+    String value();
+}