Docsp-35796: Add info about new Sync Schema Migrations to SDK pages

source/includes/baas-server-migration-note.rst

@@ -0,0 +1,22 @@
+You can update your data model after you define it. The process of changing your 
+Realm object schemas depends on whether you are working with a synced realm or 
+an unsynced (local-only) realm.
+
+Update a Data Model in a Synced Realm
+-------------------------------------
+If your app uses Atlas Device Sync to synchronize data with MongoDB Atlas, and 
+you are working with a synced realm, schema changes are handled differently.
+
+Synced realms:
+
+- Support making non-breaking and breaking changes. For more information, refer to :ref:`Breaking Changes <destructive-changes-synced-schema>` in the App Services documentation.
+- Support server-side versioning. Device SDKs do not currently support client-side 
+  schema versioning in synced realms.
+- Automatically migrate objects to the latest server-side schema version without 
+  requiring a manual migration.
+
+When working with a synced realm, you can update your schema in Atlas App Services 
+and Device Sync will update the local realm file automatically the next time it 
+connects. For more information on making server-side schema changes and handling 
+the differences between the server-side schema and your client data model, refer 
+to the :ref:`Update a Data Model <synced-schema-overview>` page in the App Services documentation.

source/includes/tip-bypass-migration.rst

@@ -0,0 +1,10 @@
+.. tip:: Bypass Migration During Development
+
+   When **developing or debugging** your application, you may prefer to delete the
+   realm instead of migrating it. Use the
+   :realm-react-sdk:`BaseConfiguration.deleteRealmIfMigrationNeeded
+   <types/Realm.BaseConfiguration.html>` property to delete the database automatically
+   when a schema mismatch requires a migration. 
+
+   Ensure that this property is always set to ``false`` for production apps.
+   **Never release an app to production with this property set to true.**

source/sdk/dotnet/model-data/change-an-object-model.txt

@@ -10,19 +10,18 @@ Change an Object Model - .NET SDK
 .. contents:: On this page
    :local:
    :backlinks: none
-   :depth: 2
+   :depth: 3
    :class: singlecol
 
 .. _dotnet-schema-version:
 
-Overview
---------
-A **migration** transforms an existing realm and its objects from its
-current :ref:`Realm Schema version <dotnet-schema-version>` to a newer one.
-Application data models typically change over time to accommodate new
-requirements and features. Migrations give you the flexibility to
-automatically update your existing application data whenever a client
-application upgrades to a newer version.
+.. include:: /includes/baas-server-migration-note.rst
+
+Update a Data Model in an Unsynced (Local-Only) Realm
+-----------------------------------------------------
+
+Data Model Changes
+~~~~~~~~~~~~~~~~~~
 
 Consider the following example, in which we have a ``RealmObject`` 
 called "Person":
@@ -40,7 +39,7 @@ At this point, there is a mismatch between the model and any saved data, and
 an exception will be thrown when you try to open the realm.
 
 Schema Version
---------------
+~~~~~~~~~~~~~~
 
 The **schema version** identifies the state of a :ref:`Realm Schema
 <dotnet-realm-schema>` at some point in time. Realm tracks the schema
@@ -62,7 +61,7 @@ the realm defaults to version ``0``.
    :ref:`object schemas <dotnet-object-schema>`.
 
 Migrate a Schema
-----------------
+~~~~~~~~~~~~~~~~
 
 .. _dotnet-og-schema:
 
@@ -91,7 +90,7 @@ A realm using schema version ``1`` has a ``Person`` object type:
 .. _dotnet-add-a-property:
 
 Add a Property
---------------
+``````````````
 
 The following example adds a ``LastName`` property to the
 :ref:`original Person schema <dotnet-og-schema>`:
@@ -103,7 +102,7 @@ The following example adds a ``LastName`` property to the
 .. _dotnet-delete-a-property:
 
 Delete a Property
------------------
+`````````````````
 
 The following example uses a combined
 ``FullName`` property instead of the separate ``FirstName`` and
@@ -117,7 +116,7 @@ The following example uses a combined
 .. _dotnet-rename-a-property:
 
 Modify a Property Type or Rename a Property
--------------------------------------------
+```````````````````````````````````````````
 
 The following example modifies the ``Age`` property in the
 :ref:`original Person schema <dotnet-og-schema>` by
@@ -129,18 +128,8 @@ renaming it to ``Birthday`` and changing the type to ``DateTimeOffset``:
 
 .. _dotnet-migration-function:
 
-Migration Functions
--------------------
-
-.. tip:: Bypass Migration During Development
-
-   When developing or debugging your application, you may prefer to delete 
-   the realm instead of migrating it. Use the 
-   :dotnet-sdk:`ShouldDeleteIfMigrationNeeded <reference/Realms.RealmConfiguration.html#Realms_RealmConfiguration_ShouldDeleteIfMigrationNeeded>` 
-   flag to delete the database automatically when a schema mismatch would
-   require a migration. 
-
-   Never release an app to production with this flag set to ``true``.
+Create a Migration Function
+```````````````````````````
 
 To migrate the realm to conform to the updated ``Person`` schema,
 set the realm's :ref:`schema version <dotnet-schema-version>` to
@@ -152,3 +141,5 @@ properties and the value of ``Birthday`` based on ``Age``:
    :language: csharp
    :emphasize-lines: 3, 21, 25, 31
    :linenos:
+
+.. include:: /includes/tip-bypass-migration.rst

source/sdk/flutter/realm-database/model-data/update-realm-object-schema.txt

@@ -8,10 +8,14 @@ Update a Realm Object Schema - Flutter SDK
 .. contents:: On this page
    :local:
    :backlinks: none
-   :depth: 2
+   :depth: 3
    :class: singlecol
 
-You can change the schema of a Realm object after you first create it.
+.. include:: /includes/baas-server-migration-note.rst
+
+Update a Data Model in an Unsynced (Local-Only) Realm
+-----------------------------------------------------
+
 Depending on the type of changes you make to the schema, the changes can be either
 automatically applied or require a manual update to the new schema.
 Manual schema updates are called **migrations** in Realm.
@@ -24,25 +28,10 @@ You must perform a manual migration for all other schema changes.
 For more information, refer to the :ref:`Manually Migrate Schema section
 <flutter-manually-migrate-schema>`.
 
-.. tip:: Bypass Migration During Development
-
-   When developing or debugging your application, you may prefer to delete
-   the realm instead of migrating it. Use the
-   :flutter-sdk:`LocalConfiguration.shouldDeleteIfMigrationNeeded <realm/LocalConfiguration/shouldDeleteIfMigrationNeeded.html>`
-   property to delete the database automatically when a schema mismatch
-   requires a migration.
-
-.. important:: Modify Schema Properties of a Synced Realm
-
-   The contents on this page only apply to local realms.
-   Schema migration functions differently for Realm using Atlas Device Sync
-   to synchronize data with MongoDB Atlas.
-   Refer to the :ref:`Updating the Schema of a Synced Realm section <flutter-update-schema-of-synced-realm>`.
-
 .. _flutter-schema-version:
 
 Schema Version
---------------
+~~~~~~~~~~~~~~
 
 A **schema version** identifies the state of a :ref:`realm schema
 <flutter-realm-schema>` at some point in time. Realm tracks the
@@ -64,15 +53,15 @@ object schemas.
 .. _flutter-automatically-update-schema:
 
 Automatically Update Schema
----------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Realm can automatically migrate added and deleted properties.
 You must update the schema version when you make these changes.
 
 .. _flutter-add-a-property:
 
 Add a Property
-~~~~~~~~~~~~~~
+``````````````
 
 To add a property to a schema:
 
@@ -101,7 +90,7 @@ To add a property to a schema:
 .. _flutter-delete-a-property:
 
 Delete a Property
-~~~~~~~~~~~~~~~~~
+`````````````````
 
 To delete a property from a schema:
 
@@ -128,7 +117,7 @@ Deleting a property does not impact existing objects.
 .. _flutter-manually-migrate-schema:
 
 Manually Migrate Schema
------------------------
+~~~~~~~~~~~~~~~~~~~~~~~
 
 For more complex schema updates, Realm requires you to manually migrate
 old instances of a given object to the new schema.
@@ -152,7 +141,7 @@ The following sections explain how to perform various migration operations.
 .. _flutter-delete-object-type:
 
 Delete an Object Type
-~~~~~~~~~~~~~~~~~~~~~
+`````````````````````
 
 To delete all objects of a type from your realm, pass a string representation
 of the object schema's name to :flutter-sdk:`Migration.deleteType() <realm/Migration/deleteType.html>`.
@@ -166,7 +155,7 @@ but the new version of the schema does not.
 .. _flutter-rename-property:
 
 Rename a Property
-~~~~~~~~~~~~~~~~~
+`````````````````
 
 Rename a schema property with :flutter-sdk:`Migration.renameProperty()
 <realm/Migration/renameProperty.html>`.
@@ -177,7 +166,7 @@ Rename a schema property with :flutter-sdk:`Migration.renameProperty()
 .. _flutter-other-migration-tasks:
 
 Other Migration Tasks
-~~~~~~~~~~~~~~~~~~~~~
+`````````````````````
 
 To perform other realm schema migrations, use the following properties of
 the ``Migration`` object in your migration callback function:
@@ -200,16 +189,4 @@ use the :flutter-sdk:`RealmObjectBase.dynamic <realm/RealmObjectBase/dynamic.htm
 .. literalinclude:: /examples/generated/flutter/migrations_test.snippet.migrations-other.dart
    :language: dart
 
-.. _flutter-update-schema-of-synced-realm:
-
-Updating the Schema of a Synced Realm
--------------------------------------
-
-Updating the schema of a synced realm is a separate process from updating
-the schema of a local-only realm.
-
-Synced realms do not have schema versions and automatically migrate
-objects to the latest schema. Synced realms only support non-breaking schema changes.
-
-Learn how to :ref:`modify schema properties of a synced realm
-<synced-schema-overview>`.
+.. include:: /includes/tip-bypass-migration.rst

source/sdk/java/model-data/modify-an-object-schema.txt

@@ -10,7 +10,7 @@ Change an Object Model - Java SDK
 .. contents:: On this page
    :local:
    :backlinks: none
-   :depth: 2
+   :depth: 3
    :class: singlecol
 
 .. tabs::
@@ -169,12 +169,13 @@ Change an Object Model - Java SDK
 
       You can make changes to the schema of a synchronized realm by
       modifying the :ref:`JSON Schema <configure-your-data-model>`
-      defined in your application's backend. Synchronized realms do
-      not require migration functions, since breaking changes to
-      synchronized schemas cause synchronization errors. Sync
-      handles non-breaking changes to synchronized realm schemas
-      automatically. As a result, both old versions of your schema and
-      new versions can synchronize as users upgrade their applications.
+      defined in your application's backend, or by changing the schema 
+      in your Atlas App Services app. 
+
+      Synchronized realms do not require migration functions. Breaking 
+      changes made on the client cause synchronization errors, but non-breaking 
+      changes are handled automatically. As a result, either version of your 
+      schema can synchronize as users upgrade their applications.
 
       To learn more about schema changes to synchronized realms,
       see :ref:`synced schema changes <synced-schema-overview>`.