Document recording the latest migration id in the model snapshot (#5270)

See dotnet/efcore#37688

Author: roji

entity-framework/core/managing-schemas/migrations/teams.md

@@ -2,56 +2,33 @@
 title: Migrations in Team Environments - EF Core
 description: Best practices for managing migrations and resolving conflicts in team environments with Entity Framework Core
 author: SamMonoRT
-ms.date: 10/30/2017
+ms.date: 02/18/2026
 uid: core/managing-schemas/migrations/teams
 ---
 # Migrations in Team Environments
 
-When working with Migrations in team environments, pay extra attention to the model snapshot file. This file can tell you if your teammate's migration merges cleanly with yours or if you need to resolve a conflict by re-creating your
-migration before sharing it.
+When working with Migrations in team environments, various problems can arise when migrations are added by multiple developers around the same time; note that migrations aren't simply SQL scripts but also include a snapshot of the model at the time of that migration.
 
-## Merging
+For example, imagine developer A and B both create work branches at the same time, and generate a migration in their branches. If developer A merges their branch and then developer B does the same, the latest migration (developer B's) will have a context snapshot that does not include the changes from developer A's migration. This can cause various forms of corruption in later migrations.
 
-When you merge migrations from your teammates, you may get conflicts in your model snapshot file. If both changes are unrelated, the merge is trivial and the two migrations can coexist. For example, you may get a merge conflict in the customer entity type configuration that looks like this:
+As a result, it is highly recommended to coordinate in advance and to avoid working concurrently on migrations in multiple branches when possible.
 
-```output
-<<<<<<< Mine
-b.Property<bool>("Deactivated");
-=======
-b.Property<int>("LoyaltyPoints");
->>>>>>> Theirs
-```
+## Detecting diverged migration trees
 
-Since both of these properties need to exist in the final model, complete the merge by adding both properties. In many
-cases, your version control system may automatically merge such changes for you.
+> [!NOTE]
+> This feature is being introduced in EF Core 11 from preview-3 onwards.
 
-```csharp
-b.Property<bool>("Deactivated");
-b.Property<int>("LoyaltyPoints");
-```
+Starting with EF 11, the model snapshot records the ID of the latest migration. This means that if two developers each create a migration on separate branches, merging those branches will produce a source control conflict in the model snapshot file — since both branches modify the latest migration ID. This conflict is an important signal: it tells you that the migration trees have diverged, and one of them must be discarded before proceeding.
 
-In these cases, your migration and your teammate's migration are independent of each other. Since either of them could be applied first, you don't need to make any additional changes to your migration before sharing it with your team.
+To resolve this, follow the steps in [Resolving diverged migration trees](#resolving-diverged-migration-trees) below: abort the merge, remove your migration (keeping your model changes), merge your teammate's changes, and then re-add your migration.
 
-## Resolving conflicts
+## Resolving diverged migration trees
 
-Sometimes you encounter a true conflict when merging the model snapshot model. For example, you and your teammate may each have renamed the same property.
-
-```output
-<<<<<<< Mine
-b.Property<string>("Username");
-=======
-b.Property<string>("Alias");
->>>>>>> Theirs
-```
-
-If you encounter this kind of conflict, resolve it by re-creating your migration. Follow these steps:
+If, when merging a branch, a diverged migration tree is detected, resolve it by re-creating your migration. Follow these steps:
 
 1. Abort the merge and rollback to your working directory before the merge
 2. Remove your migration (but keep your model changes)
 3. Merge your teammate's changes into your working directory
 4. Re-add your migration
 
-After doing this, the two migrations can be applied in the correct order. Their migration is applied first, renaming
-the column to *Alias*, thereafter your migration renames it to *Username*.
-
-Your migration can safely be shared with the rest of the team.
+After doing this, your migration is cleanly based on top of any migrations that have been added in the other branch, and its context snapshot contains all previous changes. Your migration can now be safely shared with the rest of the team.

entity-framework/core/what-is-new/ef-core-11.0/whatsnew.md

@@ -173,6 +173,16 @@ This feature was contributed by [@JoasE](https://github.com/JoasE) - many thanks
 
 ## Migrations
 
+<a name="migrations-snapshot-latest-id"></a>
+
+### Latest migration ID recorded in model snapshot
+
+When working in team environments, it's common for multiple developers to create migrations on separate branches. When these branches are merged, the migration trees can diverge, leading to issues that are sometimes difficult to detect.
+
+Starting with EF Core 11, the model snapshot now records the ID of the latest migration. When two developers create migrations on divergent branches, both branches will modify this value in the model snapshot, causing a source control merge conflict. This conflict alerts the team that they need to resolve the divergence - typically by discarding one of the migration trees and creating a new, unified migration.
+
+For more information on managing migrations in team environments, see [Migrations in Team Environments](xref:core/managing-schemas/migrations/teams).
+
 <a name="migrations-add-and-apply"></a>
 
 ### Create and apply migrations in one step