From 5ca75395e15fc4da838072af13ccd528d8a13f25 Mon Sep 17 00:00:00 2001 From: Zach Klippenstein Date: Wed, 17 Jun 2020 10:30:48 -0700 Subject: [PATCH] Rename VeryExperimentalWorkflow opt-in annotation to ExperimentalWorkflow. The new name is more idiomatic, and the "very" prefix was only used to point out that, pre-1.0, the entire library was "experimental" in a sense. --- workflow-core/api/workflow-core.api | 6 ++-- ...talWorkflow.kt => ExperimentalWorkflow.kt} | 7 ++-- .../com/squareup/workflow/LaunchWorkflow.kt | 4 +-- .../diagnostic/ChainedDiagnosticListener.kt | 4 +-- .../DebugSnapshotRecordingListener.kt | 4 +-- .../SimpleLoggingDiagnosticListener.kt | 4 +-- .../diagnostic/WorkflowDiagnosticListener.kt | 34 +++++++++---------- .../com/squareup/workflow/internal/Workers.kt | 4 +-- .../workflow/internal/WorkflowLoop.kt | 4 +-- .../workflow/internal/WorkflowNode.kt | 4 +-- .../workflow/internal/WorkflowRunner.kt | 4 +-- .../DebugSnapshotRecordingListenerTest.kt | 4 +-- .../tracing/TracingDiagnosticListener.kt | 4 +-- 13 files changed, 44 insertions(+), 43 deletions(-) rename workflow-core/src/main/java/com/squareup/workflow/{VeryExperimentalWorkflow.kt => ExperimentalWorkflow.kt} (80%) diff --git a/workflow-core/api/workflow-core.api b/workflow-core/api/workflow-core.api index 9616b2045d..0532ed3b43 100644 --- a/workflow-core/api/workflow-core.api +++ b/workflow-core/api/workflow-core.api @@ -11,6 +11,9 @@ public final class com/squareup/workflow/EventHandlerKt { public static final fun invoke (Lcom/squareup/workflow/EventHandler;)V } +public abstract interface annotation class com/squareup/workflow/ExperimentalWorkflow : java/lang/annotation/Annotation { +} + public abstract class com/squareup/workflow/LifecycleWorker : com/squareup/workflow/Worker { public fun ()V public fun doesSameWorkAs (Lcom/squareup/workflow/Worker;)Z @@ -144,9 +147,6 @@ public final class com/squareup/workflow/TypedWorker : com/squareup/workflow/Wor public fun toString ()Ljava/lang/String; } -public abstract interface annotation class com/squareup/workflow/VeryExperimentalWorkflow : java/lang/annotation/Annotation { -} - public abstract interface class com/squareup/workflow/Worker { public static final field Companion Lcom/squareup/workflow/Worker$Companion; public abstract fun doesSameWorkAs (Lcom/squareup/workflow/Worker;)Z diff --git a/workflow-core/src/main/java/com/squareup/workflow/VeryExperimentalWorkflow.kt b/workflow-core/src/main/java/com/squareup/workflow/ExperimentalWorkflow.kt similarity index 80% rename from workflow-core/src/main/java/com/squareup/workflow/VeryExperimentalWorkflow.kt rename to workflow-core/src/main/java/com/squareup/workflow/ExperimentalWorkflow.kt index 2408bfff0b..cb5b67dc77 100644 --- a/workflow-core/src/main/java/com/squareup/workflow/VeryExperimentalWorkflow.kt +++ b/workflow-core/src/main/java/com/squareup/workflow/ExperimentalWorkflow.kt @@ -20,10 +20,11 @@ import kotlin.annotation.AnnotationRetention.BINARY /** * Marks Workflow APIs that are extremely likely to change in future versions, rely themselves on - * other unstable, experimental APIs, and SHOULD NOT be used in production code. Proceed with - * caution, and be ready to have the rug pulled out from under you. + * other unstable, experimental APIs, and SHOULD NOT be used in library code or app code that you + * are not prepared to update when changing even minor workflow versions. Proceed with caution, and + * be ready to have the rug pulled out from under you. */ @MustBeDocumented @Retention(value = BINARY) @RequiresOptIn(level = ERROR) -annotation class VeryExperimentalWorkflow +annotation class ExperimentalWorkflow diff --git a/workflow-runtime/src/main/java/com/squareup/workflow/LaunchWorkflow.kt b/workflow-runtime/src/main/java/com/squareup/workflow/LaunchWorkflow.kt index 95a843e588..c8832cbd4e 100644 --- a/workflow-runtime/src/main/java/com/squareup/workflow/LaunchWorkflow.kt +++ b/workflow-runtime/src/main/java/com/squareup/workflow/LaunchWorkflow.kt @@ -209,7 +209,7 @@ fun launchWorkflowIn( * A [StateFlow] of [RenderingAndSnapshot]s that will emit any time the root workflow creates a new * rendering. */ -@OptIn(ExperimentalCoroutinesApi::class, VeryExperimentalWorkflow::class) +@OptIn(ExperimentalCoroutinesApi::class, ExperimentalWorkflow::class) fun renderWorkflowIn( workflow: Workflow, scope: CoroutineScope, @@ -268,7 +268,7 @@ fun renderWorkflowIn( @OptIn( ExperimentalCoroutinesApi::class, FlowPreview::class, - VeryExperimentalWorkflow::class + ExperimentalWorkflow::class ) @Suppress("LongParameterList") internal fun launchWorkflowImpl( diff --git a/workflow-runtime/src/main/java/com/squareup/workflow/diagnostic/ChainedDiagnosticListener.kt b/workflow-runtime/src/main/java/com/squareup/workflow/diagnostic/ChainedDiagnosticListener.kt index 62e6a6fc15..e7bead656f 100644 --- a/workflow-runtime/src/main/java/com/squareup/workflow/diagnostic/ChainedDiagnosticListener.kt +++ b/workflow-runtime/src/main/java/com/squareup/workflow/diagnostic/ChainedDiagnosticListener.kt @@ -15,7 +15,7 @@ */ package com.squareup.workflow.diagnostic -import com.squareup.workflow.VeryExperimentalWorkflow +import com.squareup.workflow.ExperimentalWorkflow import com.squareup.workflow.WorkflowAction import kotlinx.coroutines.CoroutineScope @@ -31,7 +31,7 @@ fun WorkflowDiagnosticListener.andThen( .apply { addVisitor(next) } } -@OptIn(VeryExperimentalWorkflow::class) +@OptIn(ExperimentalWorkflow::class) @Suppress("TooManyFunctions") internal class ChainedDiagnosticListener( listener: WorkflowDiagnosticListener diff --git a/workflow-runtime/src/main/java/com/squareup/workflow/diagnostic/DebugSnapshotRecordingListener.kt b/workflow-runtime/src/main/java/com/squareup/workflow/diagnostic/DebugSnapshotRecordingListener.kt index c337bdf2c8..440f4cfde9 100644 --- a/workflow-runtime/src/main/java/com/squareup/workflow/diagnostic/DebugSnapshotRecordingListener.kt +++ b/workflow-runtime/src/main/java/com/squareup/workflow/diagnostic/DebugSnapshotRecordingListener.kt @@ -15,7 +15,7 @@ */ package com.squareup.workflow.diagnostic -import com.squareup.workflow.VeryExperimentalWorkflow +import com.squareup.workflow.ExperimentalWorkflow import com.squareup.workflow.WorkflowAction import com.squareup.workflow.diagnostic.WorkflowHierarchyDebugSnapshot.ChildWorker import com.squareup.workflow.diagnostic.WorkflowHierarchyDebugSnapshot.ChildWorkflow @@ -29,7 +29,7 @@ import com.squareup.workflow.diagnostic.WorkflowUpdateDebugInfo.Source.Worker * A [WorkflowDiagnosticListener] that records [WorkflowHierarchyDebugSnapshot]s and * [WorkflowUpdateDebugInfo]s and sends them to [debugger] after each render pass. */ -@VeryExperimentalWorkflow +@ExperimentalWorkflow @Suppress("TooManyFunctions") class DebugSnapshotRecordingListener( private val debugger: (WorkflowHierarchyDebugSnapshot, WorkflowUpdateDebugInfo?) -> Unit diff --git a/workflow-runtime/src/main/java/com/squareup/workflow/diagnostic/SimpleLoggingDiagnosticListener.kt b/workflow-runtime/src/main/java/com/squareup/workflow/diagnostic/SimpleLoggingDiagnosticListener.kt index ab5cb137b9..1305ad7484 100644 --- a/workflow-runtime/src/main/java/com/squareup/workflow/diagnostic/SimpleLoggingDiagnosticListener.kt +++ b/workflow-runtime/src/main/java/com/squareup/workflow/diagnostic/SimpleLoggingDiagnosticListener.kt @@ -15,14 +15,14 @@ */ package com.squareup.workflow.diagnostic -import com.squareup.workflow.VeryExperimentalWorkflow +import com.squareup.workflow.ExperimentalWorkflow import com.squareup.workflow.WorkflowAction import kotlinx.coroutines.CoroutineScope /** * A [WorkflowDiagnosticListener] that just prints all events using [println]. */ -@OptIn(VeryExperimentalWorkflow::class) +@OptIn(ExperimentalWorkflow::class) @Suppress("TooManyFunctions") open class SimpleLoggingDiagnosticListener : WorkflowDiagnosticListener { diff --git a/workflow-runtime/src/main/java/com/squareup/workflow/diagnostic/WorkflowDiagnosticListener.kt b/workflow-runtime/src/main/java/com/squareup/workflow/diagnostic/WorkflowDiagnosticListener.kt index e4a05c88ec..9d170c4a9f 100644 --- a/workflow-runtime/src/main/java/com/squareup/workflow/diagnostic/WorkflowDiagnosticListener.kt +++ b/workflow-runtime/src/main/java/com/squareup/workflow/diagnostic/WorkflowDiagnosticListener.kt @@ -15,7 +15,7 @@ */ package com.squareup.workflow.diagnostic -import com.squareup.workflow.VeryExperimentalWorkflow +import com.squareup.workflow.ExperimentalWorkflow import com.squareup.workflow.WorkflowAction import kotlinx.coroutines.CoroutineScope @@ -76,7 +76,7 @@ interface WorkflowDiagnosticListener { * * Corresponds to [onAfterRenderPass]. */ - @VeryExperimentalWorkflow + @ExperimentalWorkflow fun onBeforeRenderPass(props: Any?) = Unit /** @@ -85,7 +85,7 @@ interface WorkflowDiagnosticListener { * @param workflowId The ID of the workflow for this event. If null, the props for the root * workflow changed. [oldState] and [newState] will always be null in that case. */ - @VeryExperimentalWorkflow + @ExperimentalWorkflow fun onPropsChanged( workflowId: Long?, oldProps: Any?, @@ -99,7 +99,7 @@ interface WorkflowDiagnosticListener { * * Corresponds to [onAfterWorkflowRendered]. */ - @VeryExperimentalWorkflow + @ExperimentalWorkflow fun onBeforeWorkflowRendered( workflowId: Long, props: Any?, @@ -111,7 +111,7 @@ interface WorkflowDiagnosticListener { * * Corresponds to [onBeforeWorkflowRendered]. */ - @VeryExperimentalWorkflow + @ExperimentalWorkflow fun onAfterWorkflowRendered( workflowId: Long, rendering: Any? @@ -122,7 +122,7 @@ interface WorkflowDiagnosticListener { * * Corresponds to [onBeforeRenderPass]. */ - @VeryExperimentalWorkflow + @ExperimentalWorkflow fun onAfterRenderPass(rendering: Any?) = Unit /** @@ -131,7 +131,7 @@ interface WorkflowDiagnosticListener { * * Corresponds to [onAfterSnapshotPass]. */ - @VeryExperimentalWorkflow + @ExperimentalWorkflow fun onBeforeSnapshotPass() = Unit /** @@ -140,7 +140,7 @@ interface WorkflowDiagnosticListener { * * Corresponds to [onBeforeSnapshotPass]. */ - @VeryExperimentalWorkflow + @ExperimentalWorkflow fun onAfterSnapshotPass() = Unit // endregion @@ -154,7 +154,7 @@ interface WorkflowDiagnosticListener { * * Corresponds to [onRuntimeStopped]. */ - @VeryExperimentalWorkflow + @ExperimentalWorkflow fun onRuntimeStarted( workflowScope: CoroutineScope, rootWorkflowType: String @@ -166,7 +166,7 @@ interface WorkflowDiagnosticListener { * * Corresponds to [onRuntimeStarted]. */ - @VeryExperimentalWorkflow + @ExperimentalWorkflow fun onRuntimeStopped() = Unit /** @@ -185,7 +185,7 @@ interface WorkflowDiagnosticListener { * [initialState][com.squareup.workflow.StatefulWorkflow.initialState]. * @param restoredFromSnapshot True iff the snapshot parameter to `initialState` was non-null. */ - @VeryExperimentalWorkflow + @ExperimentalWorkflow @Suppress("LongParameterList") fun onWorkflowStarted( workflowId: Long, @@ -204,7 +204,7 @@ interface WorkflowDiagnosticListener { * * @param workflowId The ID of the workflow that stopped. */ - @VeryExperimentalWorkflow + @ExperimentalWorkflow fun onWorkflowStopped(workflowId: Long) = Unit /** @@ -218,7 +218,7 @@ interface WorkflowDiagnosticListener { * @param key The key passed to `runningWorker` by [parentWorkflowId]. * @param description A string description of the worker. Contains the worker's `toString`. */ - @VeryExperimentalWorkflow + @ExperimentalWorkflow fun onWorkerStarted( workerId: Long, parentWorkflowId: Long, @@ -235,7 +235,7 @@ interface WorkflowDiagnosticListener { * @param workerId The ID of the worker that stopped. * @param parentWorkflowId The ID of the workflow that was running this worker. */ - @VeryExperimentalWorkflow + @ExperimentalWorkflow fun onWorkerStopped( workerId: Long, parentWorkflowId: Long @@ -255,7 +255,7 @@ interface WorkflowDiagnosticListener { * receive the output. * @param output The value that the worker output. */ - @VeryExperimentalWorkflow + @ExperimentalWorkflow fun onWorkerOutput( workerId: Long, parentWorkflowId: Long, @@ -271,7 +271,7 @@ interface WorkflowDiagnosticListener { * corresponding [WorkflowAction]. * @param action The [WorkflowAction] that will be executed by [workflowId]. */ - @VeryExperimentalWorkflow + @ExperimentalWorkflow fun onSinkReceived( workflowId: Long, action: WorkflowAction<*, *> @@ -290,7 +290,7 @@ interface WorkflowDiagnosticListener { * the state, this will be the same value as [oldState]. * @param output The output value returned from [action]. */ - @VeryExperimentalWorkflow + @ExperimentalWorkflow fun onWorkflowAction( workflowId: Long, action: WorkflowAction<*, *>, diff --git a/workflow-runtime/src/main/java/com/squareup/workflow/internal/Workers.kt b/workflow-runtime/src/main/java/com/squareup/workflow/internal/Workers.kt index 2c367ec002..5856bcc7e6 100644 --- a/workflow-runtime/src/main/java/com/squareup/workflow/internal/Workers.kt +++ b/workflow-runtime/src/main/java/com/squareup/workflow/internal/Workers.kt @@ -15,7 +15,7 @@ */ package com.squareup.workflow.internal -import com.squareup.workflow.VeryExperimentalWorkflow +import com.squareup.workflow.ExperimentalWorkflow import com.squareup.workflow.Worker import com.squareup.workflow.diagnostic.WorkflowDiagnosticListener import kotlinx.coroutines.CoroutineName @@ -79,7 +79,7 @@ private fun Worker.runWithNullCheck(): Flow = "If this is a test mock, make sure you mock the run() method!" ) -@OptIn(VeryExperimentalWorkflow::class) +@OptIn(ExperimentalWorkflow::class) private fun Flow.wireUpDebugger( workerDiagnosticId: Long, workflowDiagnosticId: Long, diff --git a/workflow-runtime/src/main/java/com/squareup/workflow/internal/WorkflowLoop.kt b/workflow-runtime/src/main/java/com/squareup/workflow/internal/WorkflowLoop.kt index d848cd77ae..ad223fc3f8 100644 --- a/workflow-runtime/src/main/java/com/squareup/workflow/internal/WorkflowLoop.kt +++ b/workflow-runtime/src/main/java/com/squareup/workflow/internal/WorkflowLoop.kt @@ -18,7 +18,7 @@ package com.squareup.workflow.internal import com.squareup.workflow.RenderingAndSnapshot import com.squareup.workflow.Snapshot import com.squareup.workflow.StatefulWorkflow -import com.squareup.workflow.VeryExperimentalWorkflow +import com.squareup.workflow.ExperimentalWorkflow import com.squareup.workflow.diagnostic.IdCounter import com.squareup.workflow.diagnostic.WorkflowDiagnosticListener import kotlinx.coroutines.channels.consume @@ -53,7 +53,7 @@ internal interface WorkflowLoop { ): Nothing } -@OptIn(VeryExperimentalWorkflow::class) +@OptIn(ExperimentalWorkflow::class) internal open class RealWorkflowLoop : WorkflowLoop { @Suppress("LongMethod") diff --git a/workflow-runtime/src/main/java/com/squareup/workflow/internal/WorkflowNode.kt b/workflow-runtime/src/main/java/com/squareup/workflow/internal/WorkflowNode.kt index 374e9cf68c..803ace62fa 100644 --- a/workflow-runtime/src/main/java/com/squareup/workflow/internal/WorkflowNode.kt +++ b/workflow-runtime/src/main/java/com/squareup/workflow/internal/WorkflowNode.kt @@ -17,7 +17,7 @@ package com.squareup.workflow.internal import com.squareup.workflow.Snapshot import com.squareup.workflow.StatefulWorkflow -import com.squareup.workflow.VeryExperimentalWorkflow +import com.squareup.workflow.ExperimentalWorkflow import com.squareup.workflow.Worker import com.squareup.workflow.Workflow import com.squareup.workflow.WorkflowAction @@ -50,7 +50,7 @@ import kotlin.coroutines.EmptyCoroutineContext * hard-coded values added to worker contexts. It must not contain a [Job] element (it would violate * structured concurrency). */ -@OptIn(VeryExperimentalWorkflow::class) +@OptIn(ExperimentalWorkflow::class) internal class WorkflowNode( val id: WorkflowId, workflow: StatefulWorkflow, diff --git a/workflow-runtime/src/main/java/com/squareup/workflow/internal/WorkflowRunner.kt b/workflow-runtime/src/main/java/com/squareup/workflow/internal/WorkflowRunner.kt index df748b3d60..8787a518d4 100644 --- a/workflow-runtime/src/main/java/com/squareup/workflow/internal/WorkflowRunner.kt +++ b/workflow-runtime/src/main/java/com/squareup/workflow/internal/WorkflowRunner.kt @@ -18,7 +18,7 @@ package com.squareup.workflow.internal import com.squareup.workflow.RenderingAndSnapshot import com.squareup.workflow.Snapshot import com.squareup.workflow.StatefulWorkflow -import com.squareup.workflow.VeryExperimentalWorkflow +import com.squareup.workflow.ExperimentalWorkflow import com.squareup.workflow.Workflow import com.squareup.workflow.diagnostic.IdCounter import com.squareup.workflow.diagnostic.WorkflowDiagnosticListener @@ -32,7 +32,7 @@ import kotlinx.coroutines.flow.produceIn import kotlinx.coroutines.selects.select import kotlin.coroutines.EmptyCoroutineContext -@OptIn(ExperimentalCoroutinesApi::class, VeryExperimentalWorkflow::class) +@OptIn(ExperimentalCoroutinesApi::class, ExperimentalWorkflow::class) internal class WorkflowRunner( scope: CoroutineScope, protoWorkflow: Workflow, diff --git a/workflow-runtime/src/test/java/com/squareup/workflow/diagnostic/DebugSnapshotRecordingListenerTest.kt b/workflow-runtime/src/test/java/com/squareup/workflow/diagnostic/DebugSnapshotRecordingListenerTest.kt index f360516021..968e9b6b58 100644 --- a/workflow-runtime/src/test/java/com/squareup/workflow/diagnostic/DebugSnapshotRecordingListenerTest.kt +++ b/workflow-runtime/src/test/java/com/squareup/workflow/diagnostic/DebugSnapshotRecordingListenerTest.kt @@ -15,7 +15,7 @@ */ package com.squareup.workflow.diagnostic -import com.squareup.workflow.VeryExperimentalWorkflow +import com.squareup.workflow.ExperimentalWorkflow import com.squareup.workflow.WorkflowAction.Companion.noAction import com.squareup.workflow.diagnostic.WorkflowHierarchyDebugSnapshot.ChildWorker import com.squareup.workflow.diagnostic.WorkflowHierarchyDebugSnapshot.ChildWorkflow @@ -24,7 +24,7 @@ import com.squareup.workflow.diagnostic.WorkflowUpdateDebugInfo.Source import kotlin.test.Test import kotlin.test.assertEquals -@OptIn(VeryExperimentalWorkflow::class) +@OptIn(ExperimentalWorkflow::class) class DebugSnapshotRecordingListenerTest { private var snapshot: WorkflowHierarchyDebugSnapshot? = null diff --git a/workflow-tracing/src/main/java/com/squareup/workflow/diagnostic/tracing/TracingDiagnosticListener.kt b/workflow-tracing/src/main/java/com/squareup/workflow/diagnostic/tracing/TracingDiagnosticListener.kt index caebac5978..f3d6208c09 100644 --- a/workflow-tracing/src/main/java/com/squareup/workflow/diagnostic/tracing/TracingDiagnosticListener.kt +++ b/workflow-tracing/src/main/java/com/squareup/workflow/diagnostic/tracing/TracingDiagnosticListener.kt @@ -28,7 +28,7 @@ import com.squareup.tracing.TraceEvent.ObjectCreated import com.squareup.tracing.TraceEvent.ObjectDestroyed import com.squareup.tracing.TraceEvent.ObjectSnapshot import com.squareup.tracing.TraceLogger -import com.squareup.workflow.VeryExperimentalWorkflow +import com.squareup.workflow.ExperimentalWorkflow import com.squareup.workflow.WorkflowAction import com.squareup.workflow.diagnostic.WorkflowDiagnosticListener import kotlinx.coroutines.CoroutineScope @@ -95,7 +95,7 @@ internal fun provideLogger( * * @constructor The primary constructor is internal so that it can inject [GcDetector] for tests. */ -@OptIn(VeryExperimentalWorkflow::class) +@OptIn(ExperimentalWorkflow::class) class TracingDiagnosticListener internal constructor( private val memoryStats: MemoryStats, private val gcDetectorConstructor: GcDetectorConstructor,