From fa8cf5994d787988a331f4f19d1503a8990dedfa Mon Sep 17 00:00:00 2001 From: cbullinger Date: Wed, 6 Mar 2024 13:04:45 -0500 Subject: [PATCH] Add migration page for v2.0.0 breaking change --- .../bundle_example/lib/realm/schemas.dart | 2 +- examples/dart/test/migrate_parts.dart | 33 +++++ ...ervices_test.snippet.access-app-by-id.dart | 2 +- ..._parts.snippet.migrate-model-dart-new.dart | 13 ++ ..._parts.snippet.migrate-model-dart-old.dart | 13 ++ .../includes/flutter-v2-breaking-change.rst | 9 ++ source/sdk/flutter/migrate-to-v2.txt | 115 ++++++++++++++++++ .../model-data/define-realm-object-schema.txt | 19 ++- 8 files changed, 200 insertions(+), 6 deletions(-) create mode 100644 examples/dart/test/migrate_parts.dart create mode 100644 source/examples/generated/flutter/migrate_parts.snippet.migrate-model-dart-new.dart create mode 100644 source/examples/generated/flutter/migrate_parts.snippet.migrate-model-dart-old.dart create mode 100644 source/includes/flutter-v2-breaking-change.rst create mode 100644 source/sdk/flutter/migrate-to-v2.txt diff --git a/examples/dart/bundle_example/lib/realm/schemas.dart b/examples/dart/bundle_example/lib/realm/schemas.dart index 7f52127e4fe..a51e7a28e1d 100644 --- a/examples/dart/bundle_example/lib/realm/schemas.dart +++ b/examples/dart/bundle_example/lib/realm/schemas.dart @@ -1,6 +1,6 @@ import 'package:realm/realm.dart'; -part 'schemas.g.dart'; +part 'schemas.realm.dart'; @RealmModel() class _Car { diff --git a/examples/dart/test/migrate_parts.dart b/examples/dart/test/migrate_parts.dart new file mode 100644 index 00000000000..71db88a6b09 --- /dev/null +++ b/examples/dart/test/migrate_parts.dart @@ -0,0 +1,33 @@ +// :snippet-start: migrate-model-dart-old +// :uncomment-start: +// import 'package:realm_dart/realm.dart'; + +// part 'car.g.dart'; // :emphasize: + +// @RealmModel() +// class _Car { +// @PrimaryKey() +// late ObjectId id; + +// late String make; +// late String? model; +// late int? miles; +// } +// :uncomment-end: +// :snippet-end: + +// :snippet-start: migrate-model-dart-new +import 'package:realm_dart/realm.dart'; + +part 'car.realm.dart'; // :emphasize: + +@RealmModel() +class _Car { + @PrimaryKey() + late ObjectId id; + + late String make; + late String? model; + late int? miles; +} +// :snippet-end: diff --git a/source/examples/generated/flutter/app_services_test.snippet.access-app-by-id.dart b/source/examples/generated/flutter/app_services_test.snippet.access-app-by-id.dart index 81f1b762819..b9862c6d36c 100644 --- a/source/examples/generated/flutter/app_services_test.snippet.access-app-by-id.dart +++ b/source/examples/generated/flutter/app_services_test.snippet.access-app-by-id.dart @@ -13,7 +13,7 @@ await Isolate.spawn((List args) async { try { final backgroundApp = App.getById(appId); - // ... Access App users + // ... Access App users final user = backgroundApp?.currentUser!; // Use the App and user as needed. diff --git a/source/examples/generated/flutter/migrate_parts.snippet.migrate-model-dart-new.dart b/source/examples/generated/flutter/migrate_parts.snippet.migrate-model-dart-new.dart new file mode 100644 index 00000000000..1312f1c3079 --- /dev/null +++ b/source/examples/generated/flutter/migrate_parts.snippet.migrate-model-dart-new.dart @@ -0,0 +1,13 @@ +import 'package:realm_dart/realm.dart'; + +part 'car.realm.dart'; + +@RealmModel() +class _Car { + @PrimaryKey() + late ObjectId id; + + late String make; + late String? model; + late int? miles; +} diff --git a/source/examples/generated/flutter/migrate_parts.snippet.migrate-model-dart-old.dart b/source/examples/generated/flutter/migrate_parts.snippet.migrate-model-dart-old.dart new file mode 100644 index 00000000000..0266e7362f6 --- /dev/null +++ b/source/examples/generated/flutter/migrate_parts.snippet.migrate-model-dart-old.dart @@ -0,0 +1,13 @@ +import 'package:realm_dart/realm.dart'; + +part 'car.g.dart'; + +@RealmModel() +class _Car { + @PrimaryKey() + late ObjectId id; + + late String make; + late String? model; + late int? miles; +} diff --git a/source/includes/flutter-v2-breaking-change.rst b/source/includes/flutter-v2-breaking-change.rst new file mode 100644 index 00000000000..91917ca9d50 --- /dev/null +++ b/source/includes/flutter-v2-breaking-change.rst @@ -0,0 +1,9 @@ +.. important:: Flutter SDK v2.0.0 Breaking Change to Generated Files + + Flutter SDK version 2.0.0 introduces a breaking change to the + builder. In v2.0.0 and later, all generated files use the ``.realm.dart`` + naming convention instead of ``.g.dart``. + + For information on how to handle this change and migrate an + existing app from an earlier version to version 2.0.0 or later, + refer to :ref:`flutter_upgrade-v2`. diff --git a/source/sdk/flutter/migrate-to-v2.txt b/source/sdk/flutter/migrate-to-v2.txt new file mode 100644 index 00000000000..1fbfe43258d --- /dev/null +++ b/source/sdk/flutter/migrate-to-v2.txt @@ -0,0 +1,115 @@ +.. _flutter_upgrade-v2: + +==================================== +Upgrade to Flutter SDK version 2.0.0 +==================================== + +.. meta:: + :description: Update your existing Flutter or Dart generated part files to successfully migrate to Atlas Device SDK for Flutter version 2.0.0. + :keywords: code example + +.. facet:: + :name: genre + :values: tutorial + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +The Atlas Device SDK for Flutter version 2.0.0 includes a breaking change to how the SDK generates part files for ``RealmModel`` classes. If you have an existing app built with an earlier version of the Flutter SDK, you must migrate your app to use the new version. + +Builder Changes +--------------- + +Flutter SDK version 2.0.0 updates the builder from a ``SharedPartBuilder`` to a ``PartBuilder``. As a result of this update, the part files that you generate for your ``RealmObject`` classes use a different naming convention: + +- **Flutter SDK v2.0.0 and later:** Generated part files are named ``.realm.dart``. For example, a ``schemas.dart`` file generates a ``schemas.realm.dart`` part file. +- **Earlier SDK versions:** Generated part files are named ``.g.dart``. For example, a ``schemas.dart`` file generates a ``schemas.g.dart`` part file. + +Additionally, this update to a ``PartBuilder`` means that you can use multiple builders. For example, you can combine + +For more information, refer to the following: + +- :ref:`flutter-define-realm-object-schema` +- v2.0.0 CHANGELOG +- `SharedPartBuilder class `__ Dart reference +- `PartBuilder class `__ Dart reference + + +What Do I Need to Do? +~~~~~~~~~~~~~~~~~~~~~ + +When you upgrade an existing app from an earlier version of the Flutter SDK to version 2.0.0 or later, you must update any part declarations, then rerun the generator: + +.. procedure:: + + .. step:: Update Your Existing Part Declarations + + Update all of the ``RealmObject`` part declarations in your app to use the new naming convention: + + .. literalinclude:: /examples/generated/flutter/migrate_parts.snippet. migrate-model-dart-old.dart + :language: dart + :caption: Earlier version + + .. literalinclude:: /examples/generated/flutter/migrate_parts.snippet. migrate-model-dart-new.dart + :language: dart + :caption: Version 2.0.0 + + .. step:: Re-generate the RealmObjects + + After you update all of your declarations, run ``dart run build_runner build`` or ``dart run build_runner build`` to generate the ``RealmObjects`` part files with the new ``.realm.dart`` build extension. + +.. _flutter-v2-deprecated-classes: + +Deprecated Classes +------------------ + +Flutter SDK version 2.0.0 also removed several deprecated classes and members from the SDK. + +The following table outlines which classes and members were removed and a recommended solution if any: + +.. list-table:: + :header-rows: 1 + :widths: 33 33 33 + + * - Deprecated Class or Member + - Reason + - Solution + + * - ``AppConfiguration.localAppName`` and ``AppConfiguration.localAppVersion`` + - Both members were unused. + - Remove any instances. + + * - ``ClientResetError.isFatal`` + - Always ``true``. + - Remove any instances. + + * - ``ClientResetError.sessionErrorCode`` + - Consolidated into ``SyncErrorCode`` in SDK v1.6.0. + - Use ``SyncErrorCode`` enum. + + * - ``RealmProperty.indexed`` + - Replaced by ``RealmProperty.indexType``. + - Replace as needed. + + * - ``SyncError`` constructor and ``SyncError.create`` factory + - Sync errors should only be created internally by the SDK. + - Remove any instances. + + * - ``SyncClientError``, ``SyncConnectionError``, ``SyncSessionError``, ``SyncResolveError``, ``SyncWebSocketError``, and ``GeneralSyncError`` + - Consolidated into ``SyncError`` in SDK v1.6.0. + - Use ``SyncError`` or its subclasses. + + * - ``SyncErrorCategory``, ``SyncClientErrorCode``, ``SyncConnectionErrorCode``, ``SyncSessionErrorCode``, ``SyncResolveErrorCode``, ``SyncWebsocketErrorCode``, and ``GeneralSyncErrorCode`` + - Consolidated into ``SyncErrorCode`` in SDK v1.6.0. + - Use ``SyncErrorCode`` enum. + + * - ``SyncError.codeValue``, ``SyncError.category``, and ``SyncError.detailedMessage`` + - Consolidated into ``SyncError`` in SDK v1.6.0. Messages were unused. + - Remove any category or message instances. Replace ``SyncError.codevalue`` with ``SyncError.code.code``. + + * - ``User.provider`` + - Provider is associated with each identity, so value was incorrect for users with more than one identity. + - Remove any instances. diff --git a/source/sdk/flutter/realm-database/model-data/define-realm-object-schema.txt b/source/sdk/flutter/realm-database/model-data/define-realm-object-schema.txt index fdb94d03223..e3183bacac9 100644 --- a/source/sdk/flutter/realm-database/model-data/define-realm-object-schema.txt +++ b/source/sdk/flutter/realm-database/model-data/define-realm-object-schema.txt @@ -17,6 +17,8 @@ Define a Realm Object Schema - Flutter SDK :depth: 2 :class: singlecol +.. include:: /includes/flutter-v2-breaking-change.rst + An **object schema** is a configuration object that defines the properties and relationships of a Realm object. Realm client applications define object schemas with the native class implementation in their @@ -58,6 +60,9 @@ Create Model .. step:: Create Generated File Part Directive + .. versionchanged:: v2.0.0 + **Breaking Change:** Part files are named ``.realm.dart`` instead of ``.g.dart`` + Add a part directive to include the ``RealmObject`` file that you generate in step 4 in the same package as the file you're currently working on. @@ -95,6 +100,9 @@ Create Model .. step:: Generate RealmObject + .. versionchanged:: v2.0.0 + **Breaking Change:** Generated files are named ``.realm.dart`` instead of ``.g.dart`` + Generate the ``RealmObject``, which you'll use in your application: .. tabs:: @@ -126,7 +134,7 @@ Create Model . ├── schemas.dart - ├── schemas.g.dart // newly generated file + ├── schemas.realm.dart // newly generated file ├── myapp.dart └── ...rest of application @@ -238,6 +246,9 @@ If you're using Atlas Device Sync, the name that you specify in the Generate the RealmObject ------------------------ +.. versionchanged:: v2.0.0 + **Breaking Change:** Generated files are named ``.realm.dart`` instead of ``.g.dart`` + Once you've completed your Realm model, you must generate the :flutter-sdk:`RealmObject ` class to use it in your application. @@ -264,8 +275,8 @@ Running this creates a public class in a new file in the directory where you defined the ``RealmModel`` class per the :ref:`Create Model section `. The generated file has the same base name as the file with your ``RealmModel``, -ending with ``.g.dart``. For example if the file with your ``RealmModel`` -is named ``schemas.dart``, the generated file will be ``schemas.g.dart``. +ending with ``.realm.dart``. For example if the file with your ``RealmModel`` +is named ``schemas.dart``, the generated file will be ``schemas.realm.dart``. .. note:: @@ -278,7 +289,7 @@ is named ``schemas.dart``, the generated file will be ``schemas.g.dart``. // ...import packages - part 'schemas.g.dart'; + part 'schemas.realm.dart'; @RealmModel() // ...model definition