Merge pull request #1160 from square/ray/tutorial-big-disclaimer

Updates tutorial with disclaimer about stale API

RELEASING.md

@@ -81,7 +81,7 @@
       1. `git merge --no-ff origin/yourname/kotlin-v0.1.0`
       1. `git push origin gh-pages`
 
-1. Once Maven artifacts are synced, update the workflow version used by the tutorial in
+1. _Don't do this until the tutorial gets updated._ Once Maven artifacts are synced, update the workflow version used by the tutorial in
    `samples/tutorial/build.gradle`.
 
 ### Validating Markdown

samples/tutorial/README.md

@@ -1,5 +1,25 @@
 # Tutorial
 
+## Stale Docs Warning
+
+**This tutorial is tied to an older version of Workflow, and relies on API that has been deprecated or deleted.**
+The general concepts are the same, and refactoring to the current API is straightforward,
+so it is still worthwhile to work through the tutorial in its current state until we find time to update it.
+(Track that work [here](https://github.com/square/workflow-kotlin/issues/905)
+and [here](https://github.com/square/workflow-kotlin/issues/884).)
+
+Here's a summary of what has changed, and what replaces what:
+
+- Use of `ViewRegistry` is now optional, and rare.
+  Have your renderings implement `AndroidScreen` or `ComposeScreen` to avoid it.
+- The API for binding a rendering to UI code has changed as follows, and can all
+  be avoided if you use `ComposeScreen`:
+   - `ViewFactory<in RenderingT : Any>` is replaced by `ScreenViewFactory<in ScreenT : Screen>`.
+   -`LayoutRunner<RenderingT : Any>` is replaced by `ScreenViewRunner<in ScreenT : Screen>`.
+   - `LayoutRunner.bind` is replaced by `ScreenViewFactory.fromViewBinding`.
+- `BackStackScreen` has been moved to package `com.squareup.workflow1.ui.navigation`.
+- `EditText.updateText` and `EditText.setTextChangedListener` are replaced by `TextController`
+
 ## Overview
 
 Oh hi! Looks like you want build some software with Workflows! It's a bit different from traditional

samples/tutorial/Tutorial1.md

@@ -2,7 +2,25 @@
 
 _Let's get something on the screen..._
 
-_Note that this tutorial differs slightly from the latest [documentation](https://square.github.io/workflow/). However the core concepts are the same, you can easily refactor your completed tutorial to reflect the latest API if you wish._
+## Stale Docs Warning
+
+**This tutorial is tied to an older version of Workflow, and relies on API that has been deprecated or deleted.**
+The general concepts are the same, and refactoring to the current API is straightforward,
+so it is still worthwhile to work through the tutorial in its current state until we find time to update it.
+(Track that work [here](https://github.com/square/workflow-kotlin/issues/905)
+and [here](https://github.com/square/workflow-kotlin/issues/884).)
+
+Here's a summary of what has changed, and what replaces what:
+
+- Use of `ViewRegistry` is now optional, and rare.
+  Have your renderings implement `AndroidScreen` or `ComposeScreen` to avoid it.
+- The API for binding a rendering to UI code has changed as follows, and can all
+  be avoided if you use `ComposeScreen`:
+   - `ViewFactory<in RenderingT : Any>` is replaced by `ScreenViewFactory<in ScreenT : Screen>`.
+   -`LayoutRunner<RenderingT : Any>` is replaced by `ScreenViewRunner<in ScreenT : Screen>`.
+   - `LayoutRunner.bind` is replaced by `ScreenViewFactory.fromViewBinding`.
+- `BackStackScreen` has been moved to package `com.squareup.workflow1.ui.navigation`.
+- `EditText.updateText` and `EditText.setTextChangedListener` are replaced by `TextController`
 
 ## Setup
 

samples/tutorial/Tutorial2.md

@@ -2,6 +2,26 @@
 
 _Multiple Screens and Navigation_
 
+## Stale Docs Warning
+
+**This tutorial is tied to an older version of Workflow, and relies on API that has been deprecated or deleted.**
+The general concepts are the same, and refactoring to the current API is straightforward,
+so it is still worthwhile to work through the tutorial in its current state until we find time to update it.
+(Track that work [here](https://github.com/square/workflow-kotlin/issues/905)
+and [here](https://github.com/square/workflow-kotlin/issues/884).)
+
+Here's a summary of what has changed, and what replaces what:
+
+- Use of `ViewRegistry` is now optional, and rare.
+  Have your renderings implement `AndroidScreen` or `ComposeScreen` to avoid it.
+- The API for binding a rendering to UI code has changed as follows, and can all
+  be avoided if you use `ComposeScreen`:
+   - `ViewFactory<in RenderingT : Any>` is replaced by `ScreenViewFactory<in ScreenT : Screen>`.
+   -`LayoutRunner<RenderingT : Any>` is replaced by `ScreenViewRunner<in ScreenT : Screen>`.
+   - `LayoutRunner.bind` is replaced by `ScreenViewFactory.fromViewBinding`.
+- `BackStackScreen` has been moved to package `com.squareup.workflow1.ui.navigation`.
+- `EditText.updateText` and `EditText.setTextChangedListener` are replaced by `TextController`
+
 ## Setup
 
 To follow this tutorial, launch Android Studio and open this folder (`samples/tutorial`).

samples/tutorial/Tutorial3.md

@@ -1,6 +1,24 @@
 # Step 3
 
-_State throughout a tree of workflows_
+## Stale Docs Warning
+
+**This tutorial is tied to an older version of Workflow, and relies on API that has been deprecated or deleted.**
+The general concepts are the same, and refactoring to the current API is straightforward,
+so it is still worthwhile to work through the tutorial in its current state until we find time to update it.
+(Track that work [here](https://github.com/square/workflow-kotlin/issues/905)
+and [here](https://github.com/square/workflow-kotlin/issues/884).)
+
+Here's a summary of what has changed, and what replaces what:
+
+- Use of `ViewRegistry` is now optional, and rare.
+  Have your renderings implement `AndroidScreen` or `ComposeScreen` to avoid it.
+- The API for binding a rendering to UI code has changed as follows, and can all
+  be avoided if you use `ComposeScreen`:
+   - `ViewFactory<in RenderingT : Any>` is replaced by `ScreenViewFactory<in ScreenT : Screen>`.
+   -`LayoutRunner<RenderingT : Any>` is replaced by `ScreenViewRunner<in ScreenT : Screen>`.
+   - `LayoutRunner.bind` is replaced by `ScreenViewFactory.fromViewBinding`.
+- `BackStackScreen` has been moved to package `com.squareup.workflow1.ui.navigation`.
+- `EditText.updateText` and `EditText.setTextChangedListener` are replaced by `TextController`
 
 ## Setup
 

samples/tutorial/Tutorial4.md

@@ -2,6 +2,26 @@
 
 _Refactoring and rebalancing a tree of Workflows_
 
+## Stale Docs Warning
+
+**This tutorial is tied to an older version of Workflow, and relies on API that has been deprecated or deleted.**
+The general concepts are the same, and refactoring to the current API is straightforward,
+so it is still worthwhile to work through the tutorial in its current state until we find time to update it.
+(Track that work [here](https://github.com/square/workflow-kotlin/issues/905)
+and [here](https://github.com/square/workflow-kotlin/issues/884).)
+
+Here's a summary of what has changed, and what replaces what:
+
+- Use of `ViewRegistry` is now optional, and rare.
+  Have your renderings implement `AndroidScreen` or `ComposeScreen` to avoid it.
+- The API for binding a rendering to UI code has changed as follows, and can all
+  be avoided if you use `ComposeScreen`:
+   - `ViewFactory<in RenderingT : Any>` is replaced by `ScreenViewFactory<in ScreenT : Screen>`.
+   - `LayoutRunner<RenderingT : Any>` is replaced by `ScreenViewRunner<in ScreenT : Screen>`.
+   - `LayoutRunner.bind` is replaced by `ScreenViewFactory.fromViewBinding`.
+- `BackStackScreen` has been moved to package `com.squareup.workflow1.ui.navigation`.
+- `EditText.updateText` and `EditText.setTextChangedListener` are replaced by `TextController`
+
 ## Setup
 
 To follow this tutorial, launch Android Studio and open this folder (`samples/tutorial`).

samples/tutorial/Tutorial5.md

@@ -2,6 +2,26 @@
 
 _Unit and Integration Testing Workflows_
 
+## Stale Docs Warning
+
+**This tutorial is tied to an older version of Workflow, and relies on API that has been deprecated or deleted.**
+The general concepts are the same, and refactoring to the current API is straightforward,
+so it is still worthwhile to work through the tutorial in its current state until we find time to update it.
+(Track that work [here](https://github.com/square/workflow-kotlin/issues/905)
+and [here](https://github.com/square/workflow-kotlin/issues/884).)
+
+Here's a summary of what has changed, and what replaces what:
+
+- Use of `ViewRegistry` is now optional, and rare.
+  Have your renderings implement `AndroidScreen` or `ComposeScreen` to avoid it.
+- The API for binding a rendering to UI code has changed as follows, and can all
+  be avoided if you use `ComposeScreen`:
+   - `ViewFactory<in RenderingT : Any>` is replaced by `ScreenViewFactory<in ScreenT : Screen>`.
+   - `LayoutRunner<RenderingT : Any>` is replaced by `ScreenViewRunner<in ScreenT : Screen>`.
+   - `LayoutRunner.bind` is replaced by `ScreenViewFactory.fromViewBinding`.
+- `BackStackScreen` has been moved to package `com.squareup.workflow1.ui.navigation`.
+- `EditText.updateText` and `EditText.setTextChangedListener` are replaced by `TextController`
+
 ## Setup
 
 To follow this tutorial, launch Android Studio and open this folder (`samples/tutorial`).