KEYCLOAK-14536 Add upgrading guide pointing out UserModel changes

- changes impact deployments with certain custom attributes
- changes impact SPIs subclassing UserModel

upgrading/topics/keycloak/changes.adoc

@@ -12,6 +12,17 @@ This should not affect most of the deployments, but some can be affected under s
 tried to update a user with the admin REST API and the user had some incorrect attribute changes, the update was possible. With the
 current version, the update is not possible and you will be immediately informed about the reason.
 
+==== UserModel changes
+
+The fields `username`, `email`, `firstName` and `lastName` in the `UserModel` are migrated to custom attributes as a preparation for adding more sophisticated user profiles to {project_name} in an upcoming version.
+If a database contains users with custom attributes of that exact name, the custom attributes will need to be migrated before upgrading. This migration does not occur automatically. Otherwise, they will not be read from the database anymore and possibly deleted.
+This situation implies that the `username` can now also be accessed and set via `UserModel.getFirstAttribute(UserModel.USERNAME)`. Similar implications exist for other fields.
+Implementors of SPIs subclassing the `UserModel` directly or indirectly should ensure that the behavior between `setUsername` and `setSingleAttribute(UserModel.USERNAME, ...)` (and similar for the other fields) is consistent.
+Users of the policy evaluation feature have to adapt their policies if they use the number of attributes in their evaluations since every user will now have four new attributes by default.
+
+The public API of `UserModel` has not changed, so no changes to frontend resources or SPIs accessing user data should be necessary.
+The database has also not changed, yet.
+
 === Migrating to 9.0.1
 
 ==== Legacy promise in JavaScript adapter