Primary sort order for IDoValueMigrationHandler

Untyped data object value migration handlers need to be applied before
regular value migrations because they may convert typed values to the
expected target type. A typical use case is conversion from UnknownId
to a typed target ID in case of renaming a type ID name.

A primary sort order is introduced to allow (primary) sorting
independent of the type version (which is used for secondary sorting).
The primary sort order can be used to group different types of value
migrations.

Regular value migrations (i.e. sub-classes of
AbstractDoValueMigrationHandler use
IDoValueMigrationHandler.DEFAULT_PRIMARY_SORT_ORDER and are applied
after untyped value migrations (i.e. sub-classes of
AbstractDoValueUntypedMigrationHandler) which use
IDoValueMigrationHandler.UNTYPED_PRIMARY_SORT_ORDER

379569

docs/modules/migration/partials/migration-guide-24.2.adoc

@@ -112,3 +112,15 @@ With this change the following data objects have been adjusted:
 |PermissionId
 |id
 |===
+
+[[value-migration-primary-sort-order]]
+== Primary sort order for IDoValueMigrationHandler
+
+Untyped data object value migration handlers need to be applied before regular value migrations because they may convert typed values to the expected target type.
+A typical use case is the conversion from `UnknownId` to a typed target ID in case of renaming a type ID name.
+
+Classes implementing `IDoValueMigrationHandler` directly need to implement the new method `IDoValueMigrationHandler.primarySortOrder()`.
+It's highly recommended to extend `AbstractDoValueMigrationHandler` which defines `DEFAULT_PRIMARY_SORT_ORDER` by default instead of implementing only the interface.
+
+The primary sort order can be used to group different types of value migrations.
+Regular value migrations (i.e. sub-classes of `AbstractDoValueMigrationHandler` use `IDoValueMigrationHandler.DEFAULT_PRIMARY_SORT_ORDER`) and are applied after untyped value migrations (i.e. sub-classes of `AbstractDoValueUntypedMigrationHandler`) which use `IDoValueMigrationHandler.UNTYPED_PRIMARY_SORT_ORDER`.