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

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/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`. 

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 <https://pub.dev/documentation/source_gen/latest/source_gen/SharedPartBuilder-class.html>`__ Dart reference 
+- `PartBuilder class <https://pub.dev/documentation/source_gen/latest/source_gen/PartBuilder-class.html>`__ 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. 

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 <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