Add migration page for v2.0.0 breaking change

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 {

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:

source/examples/generated/flutter/app_services_test.snippet.access-app-by-id.dart

@@ -13,7 +13,7 @@ await Isolate.spawn((List<Object> 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.

source/examples/generated/flutter/migrate_parts.snippet.migrate-model-dart-new.dart

@@ -0,0 +1,15 @@
+import 'package:realm_dart/realm.dart';
+
+// Update existing declaration from .g.dart to .realm.dart
+// part `car.g.dart`;
+part 'car.realm.dart'; 
+
+@RealmModel()
+class _Car {
+  @PrimaryKey()
+  late ObjectId id;
+
+  late String make;
+  late String? model;
+  late int? miles;
+}

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;
+}

source/examples/generated/flutter/migrate_parts.snippet.part-directive-new.dart

@@ -0,0 +1 @@
+part 'car.realm.dart'; 

source/examples/generated/flutter/migrate_parts.snippet.part-directive-old.dart

@@ -0,0 +1 @@
+part 'car.g.dart';

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 an update to the 
+    builder, which impacts how files generate. In v2.0.0 and later, all 
+    generated files use the ``.realm.dart`` naming convention instead of ``.g.dart``. 
+    This is a breaking change for existing apps and requires a migration. 
+
+    For information on how to update an existing app from an earlier 
+    version to v2.0.0 or later, refer to :ref:`flutter_upgrade-v2`. 

source/sdk/flutter.txt

@@ -28,6 +28,7 @@ Atlas Device SDK for Flutter
    Logging </sdk/flutter/logging>
    SDK Telemetry </sdk/flutter/telemetry>
    API Reference <https://pub.dev/documentation/realm/latest/>
+   Upgrade to Flutter SDK v2.0.0 </sdk/flutter/migrate-to-v2>
    Example Projects <https://github.com/realm/realm-dart-samples>
    Release Notes <https://github.com/realm/realm-dart/releases>
 

source/sdk/flutter/install.txt

@@ -168,6 +168,8 @@ except where otherwise noted.
 Update Package Version
 ----------------------
 
+.. include:: /includes/flutter-v2-breaking-change.rst
+
 To change the version of the Flutter SDK or Dart Standalone SDK in your project, 
 follow these steps.
 

source/sdk/flutter/migrate-to-v2.txt

@@ -0,0 +1,151 @@
+.. _flutter_upgrade-v2:
+
+=============================
+Upgrade to Flutter SDK v2.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
+
+Atlas Device SDK for Flutter version 2.0.0 introduces a breaking change 
+to how the SDK generates files for your data model 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. 
+
+Flutter SDK v2.0.0 also deprecates several classes and members. Refer to the 
+:ref:`flutter-v2-deprecated-classes` section on this page for information 
+on migration solutions.
+
+Builder Changes
+---------------
+
+Flutter SDK version 2.0.0 updates the SDK's ``realm_generator`` to use a ``PartBuilder`` instead of a ``SharedPartBuilder``. 
+
+As a result of this update, the generated ``RealmModel`` data model files use a new ``.realm.dart`` file extension:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 25 25 50
+
+   * - Version
+     - File Extension
+     - Example Part Directive
+
+   * - SDK v2.0.0 and later 
+     - ``.realm.dart``
+     - .. literalinclude:: /examples/generated/flutter/migrate_parts.snippet.part-directive-new.dart
+        :language: dart
+
+   * - SDK v1.9.0 and earlier 
+     - ``.g.dart`` 
+     - .. literalinclude:: /examples/generated/flutter/migrate_parts.snippet.part-directive-old.dart
+        :language: dart
+
+Additionally, the SDK's use of a ``PartBuilder`` makes it easier to use 
+multiple builders in your app. For example, combining ``realm_dart`` 
+with a serialization package builder such as ``dart_mappable`` or 
+``json_serializable``.
+
+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 regenerate the object models: 
+
+.. 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-new.dart
+           :language: dart
+           :emphasize-lines: 3-5
+
+    .. step:: Regenerate Your Object Models
+
+       .. tabs::
+
+          .. tab:: Flutter
+              :tabid: flutter 
+
+              After you update all of your declarations, regenerate your 
+              object models to use the new ``.realm.dart`` file extension.
+
+              .. code-block::
+
+                dart run realm generate
+
+          .. tab:: Dart Standalone
+              :tabid: dart 
+
+              After you update all of your declarations, regenerate your 
+              object models to use the new ``.realm.dart`` file extension.
+
+              .. code-block::
+
+                dart run realm_dart generate
+
+.. _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``
+     - 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 any instances.    
+
+   * - ``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. 

source/sdk/flutter/quick-start.txt

@@ -57,7 +57,7 @@ Some considerations when defining your Realm model class:
   Generate RealmObject Class section. This command
   outputs a public class, such as ``Car``.
 
-- Make sure to include the generated file name, such as ``part car.g.dart``,
+- Make sure to include the generated file name, such as ``part car.realm.dart``,
   before the code defining your model.
   This is required to generate the RealmObject class.
 
@@ -100,7 +100,7 @@ Now generate a RealmObject class ``Car`` from the data model class ``Car``:
 
          dart run realm_dart generate
 
-Running this creates a ``Car`` class in a ``car.g.dart`` file located in the directory
+Running this creates a ``Car`` class in a ``car.realm.dart`` file located in the directory
 where you defined the model class per the preceding Create Data Model section.
 This ``Car`` class is public and part of the same library
 as the ``_Car`` data model class.

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
+          Generated 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
+          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
+    Generated files are named ``.realm.dart`` instead of ``.g.dart`` 
+
 Once you've completed your Realm model, you must generate the
 :flutter-sdk:`RealmObject <realm/RealmObjectBase-mixin.html>` 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 <flutter-create-model>`.
 
 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