From de5be700b49d04b66d07682dafdd30f9b3cbdbbd Mon Sep 17 00:00:00 2001 From: Sydney Jodon Date: Wed, 27 Mar 2024 17:00:06 -0700 Subject: [PATCH 1/7] Add initial migration guide structure --- doc/null_safety/null_safe_migration.md | 50 ++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) create mode 100644 doc/null_safety/null_safe_migration.md diff --git a/doc/null_safety/null_safe_migration.md b/doc/null_safety/null_safe_migration.md new file mode 100644 index 000000000..8fbe7f76f --- /dev/null +++ b/doc/null_safety/null_safe_migration.md @@ -0,0 +1,50 @@ +# Dart Null Safety Migration Guide + +Steps to migrate a repo to null safety: + +1. [View resources](#step-1-view-resources) +1. [Run the preparation codemod](#step-2-run-the-preparation-codemod-coming-soon) +1. [Run the migration tool](#step-3-run-the-migration-tool) + +## Step 1: View resources + +If you haven't already, familiarize yourself with the concepts of Dart null safety with the following resources: + +- [Understanding null safety](https://dart.dev/null-safety/understanding-null-safety) article + + + +## Step 2: Run the preparation codemod (coming soon!) + + + +> ⚠️ This codemod does not exist yet, but is coming soon! + +Start out by running the `null_safety_prep` [codemod][orcm] on your repo: + +``` +dart pub global activate over_react_codemod +dart pub global run over_react_codemod:null_safety_prep +``` + +This codemod will: +- Migrate as many over_react specific use cases as possible. +- Get the repo into a state where the migration tool can be run with less manual intervention. + +## Step 3: Run the migration tool + +Run the null safety migrator tool: + +- For Workiva employees, use the [Workiva version of the migrator tool](https://github.com/Workiva/wnnbd?tab=readme-ov-file#migrating-a-package). +- Otherwise, use [Dart's migrator tool](https://dart.dev/null-safety/migration-guide#migration-tool). + +### Common migration cases + +Below are some common cases that might come up while running the migrator tool on a repo using over_react. + +#### Whether a prop should be non-nullable + + + + +[orcm]: https://github.com/Workiva/over_react_codemod From 5cfe56ffd7fcda234a508b977f4d2784f1ea89aa Mon Sep 17 00:00:00 2001 From: Sydney Jodon Date: Tue, 9 Apr 2024 15:17:25 -0600 Subject: [PATCH 2/7] Add prop nullability section --- doc/null_safety/null_safe_migration.md | 21 ++++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/doc/null_safety/null_safe_migration.md b/doc/null_safety/null_safe_migration.md index 8fbe7f76f..7eeb68b77 100644 --- a/doc/null_safety/null_safe_migration.md +++ b/doc/null_safety/null_safe_migration.md @@ -42,8 +42,27 @@ Run the null safety migrator tool: Below are some common cases that might come up while running the migrator tool on a repo using over_react. -#### Whether a prop should be non-nullable +#### Prop nullability +To determine if a prop should be nullable or not, first consider if the prop is required. + + + +> ⚠️ Making a prop required with the `late` keyword can be a breaking change if consumers are not always setting the prop. + +Below is a table of the possible options for prop nullability: + +| | Required (`late`) | Optional | +|----------------|----------------------|-----------------| +| Nullable (`?`) | `late String? prop;` | `String? prop;` | +| Non-nullable | `late String prop;` | n/a | + +- (_most common_) All **optional** props should be made **nullable**. +- **Required** props can be nullable or non-nullable: + - **Nullable**: If the prop is required, but can be explicitly set to `null`. + - **Non-nullable**: If the prop is required and should never be set to `null`. + +#### Potential Gotchas From db0d278e3c724ae5666ebe3c4b73eeddf58be815 Mon Sep 17 00:00:00 2001 From: Sydney Jodon Date: Tue, 9 Apr 2024 15:39:38 -0600 Subject: [PATCH 3/7] Add gotchas section --- doc/null_safety/null_safe_migration.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/doc/null_safety/null_safe_migration.md b/doc/null_safety/null_safe_migration.md index 7eeb68b77..bf0b23fb4 100644 --- a/doc/null_safety/null_safe_migration.md +++ b/doc/null_safety/null_safe_migration.md @@ -64,6 +64,18 @@ Below is a table of the possible options for prop nullability: #### Potential Gotchas +The migrator tool [incorrectly treats the result of emulated function calls as nullable](https://github.com/dart-lang/sdk/issues/46263). +The most common way this affects over_react is in cases like this: +```dart +// The over_react code: +var content = Dom.div()(); + +// gets incorrectly migrated to: +ReactElement? content = Dom.div()(); +``` + + [orcm]: https://github.com/Workiva/over_react_codemod From 4ad995dd5e326994c5f2bb4cf97c03944e0c4dab Mon Sep 17 00:00:00 2001 From: Sydney Jodon Date: Thu, 18 Apr 2024 15:32:21 -0700 Subject: [PATCH 4/7] Address feedback --- README.md | 1 + doc/null_safety/null_safe_migration.md | 6 +++++- 2 files changed, 6 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 7ecc24ab2..5633f272c 100644 --- a/README.md +++ b/README.md @@ -50,6 +50,7 @@ __Once you have migrated your components to `UiComponent2`__, you're ready to st - [__BuiltRedux to Redux__](doc/built_redux_to_redux.md): A guide to transitioning to OverReact Redux from BuiltRedux. - [__Flux to Redux__](doc/flux_to_redux.md): A guide to how to transition from w_flux to OverReact Redux. This guide also introduces a new architecture, Influx, that can be used for incremental refactors. - [__Dart2 Migration__](doc/dart2_migration.md): Documentation on the Dart 2 builder updates and how to transition componentry to Dart 2. +- [__Null Safety__](doc/null_safety/null_safe_migration.md): Documentation on how to migrate OverReact code to null safety.     diff --git a/doc/null_safety/null_safe_migration.md b/doc/null_safety/null_safe_migration.md index bf0b23fb4..2b130f4c5 100644 --- a/doc/null_safety/null_safe_migration.md +++ b/doc/null_safety/null_safe_migration.md @@ -1,5 +1,8 @@ # Dart Null Safety Migration Guide +> [!NOTE] +> For Workiva employees, also refer to this more detailed Workiva-specific [migration guide](https://github.com/Workiva/dart_null_tools/blob/master/workiva_migration_guide.md). + Steps to migrate a repo to null safety: 1. [View resources](#step-1-view-resources) @@ -48,7 +51,8 @@ To determine if a prop should be nullable or not, first consider if the prop is -> ⚠️ Making a prop required with the `late` keyword can be a breaking change if consumers are not always setting the prop. +> [!WARNING] +> Making a prop required with the `late` keyword can be a breaking change if consumers are not always setting the prop. Below is a table of the possible options for prop nullability: From f6cafd9c26a1e6caf093cd30302dbdc3b3833fcb Mon Sep 17 00:00:00 2001 From: Sydney Jodon Date: Thu, 18 Apr 2024 15:33:23 -0700 Subject: [PATCH 5/7] Address feedback --- doc/null_safety/null_safe_migration.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/null_safety/null_safe_migration.md b/doc/null_safety/null_safe_migration.md index 2b130f4c5..106f6d8f4 100644 --- a/doc/null_safety/null_safe_migration.md +++ b/doc/null_safety/null_safe_migration.md @@ -21,7 +21,8 @@ If you haven't already, familiarize yourself with the concepts of Dart null safe -> ⚠️ This codemod does not exist yet, but is coming soon! +> [!WARNING] +> This codemod does not exist yet, but is coming soon! Start out by running the `null_safety_prep` [codemod][orcm] on your repo: From 571cf3181c45ef6c53d6f1bd5f78df170e1e7985 Mon Sep 17 00:00:00 2001 From: Sydney Jodon Date: Thu, 18 Apr 2024 15:34:53 -0700 Subject: [PATCH 6/7] Remove todo --- doc/null_safety/null_safe_migration.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/doc/null_safety/null_safe_migration.md b/doc/null_safety/null_safe_migration.md index 106f6d8f4..1aa994ec0 100644 --- a/doc/null_safety/null_safe_migration.md +++ b/doc/null_safety/null_safe_migration.md @@ -50,8 +50,6 @@ Below are some common cases that might come up while running the migrator tool o To determine if a prop should be nullable or not, first consider if the prop is required. - - > [!WARNING] > Making a prop required with the `late` keyword can be a breaking change if consumers are not always setting the prop. From 787abd2a9ff96d276c795c080694877bed2c81a7 Mon Sep 17 00:00:00 2001 From: Sydney Jodon Date: Thu, 18 Apr 2024 15:51:52 -0700 Subject: [PATCH 7/7] Update todo --- doc/null_safety/null_safe_migration.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/doc/null_safety/null_safe_migration.md b/doc/null_safety/null_safe_migration.md index 1aa994ec0..e4004e564 100644 --- a/doc/null_safety/null_safe_migration.md +++ b/doc/null_safety/null_safe_migration.md @@ -78,7 +78,6 @@ var content = Dom.div()(); ReactElement? content = Dom.div()(); ``` - + [orcm]: https://github.com/Workiva/over_react_codemod