From 8bef55cbd4a465d0837a0901a90e0fe8e6cd5ae2 Mon Sep 17 00:00:00 2001 From: Ray Ryan Date: Mon, 22 Jan 2024 11:25:15 -0800 Subject: [PATCH] Updates tutorial with disclaimer about stale API --- RELEASING.md | 2 +- samples/tutorial/README.md | 20 ++++++++++++++++++++ samples/tutorial/Tutorial1.md | 20 +++++++++++++++++++- samples/tutorial/Tutorial2.md | 20 ++++++++++++++++++++ samples/tutorial/Tutorial3.md | 20 +++++++++++++++++++- samples/tutorial/Tutorial4.md | 20 ++++++++++++++++++++ samples/tutorial/Tutorial5.md | 20 ++++++++++++++++++++ 7 files changed, 119 insertions(+), 3 deletions(-) diff --git a/RELEASING.md b/RELEASING.md index ddb28c02c..cd8f44e68 100644 --- a/RELEASING.md +++ b/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 diff --git a/samples/tutorial/README.md b/samples/tutorial/README.md index d1fac33e3..72305195a 100644 --- a/samples/tutorial/README.md +++ b/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` is replaced by `ScreenViewFactory`. + -`LayoutRunner` is replaced by `ScreenViewRunner`. + - `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 diff --git a/samples/tutorial/Tutorial1.md b/samples/tutorial/Tutorial1.md index 15c3de490..8cc48e0d1 100644 --- a/samples/tutorial/Tutorial1.md +++ b/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` is replaced by `ScreenViewFactory`. + -`LayoutRunner` is replaced by `ScreenViewRunner`. + - `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 diff --git a/samples/tutorial/Tutorial2.md b/samples/tutorial/Tutorial2.md index 2f4da400c..3cd23782c 100644 --- a/samples/tutorial/Tutorial2.md +++ b/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` is replaced by `ScreenViewFactory`. + -`LayoutRunner` is replaced by `ScreenViewRunner`. + - `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`). diff --git a/samples/tutorial/Tutorial3.md b/samples/tutorial/Tutorial3.md index 1d6bea3ea..52e8dfd32 100644 --- a/samples/tutorial/Tutorial3.md +++ b/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` is replaced by `ScreenViewFactory`. + -`LayoutRunner` is replaced by `ScreenViewRunner`. + - `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 diff --git a/samples/tutorial/Tutorial4.md b/samples/tutorial/Tutorial4.md index d4b64c1ed..496bcd1e0 100644 --- a/samples/tutorial/Tutorial4.md +++ b/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` is replaced by `ScreenViewFactory`. + - `LayoutRunner` is replaced by `ScreenViewRunner`. + - `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`). diff --git a/samples/tutorial/Tutorial5.md b/samples/tutorial/Tutorial5.md index d0b232f79..e8da14eec 100644 --- a/samples/tutorial/Tutorial5.md +++ b/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` is replaced by `ScreenViewFactory`. + - `LayoutRunner` is replaced by `ScreenViewRunner`. + - `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`).