Add upgrade considerations for GroupPagePermission changes

docs/releases/5.1.md

@@ -116,10 +116,10 @@ permission_policy.revisions_for_moderation(user)
 permission_policy.explorable_instances(user)
 
 # proxy.editable_pages()
-permission_policy.instances_user_has_permission_for(user, "edit")
+permission_policy.instances_user_has_permission_for(user, "change")
 
 # proxy.can_edit_pages()
-permission_policy.instances_user_has_permission_for(user, "edit").exists()
+permission_policy.instances_user_has_permission_for(user, "change").exists()
 
 # proxy.publishable_pages()
 permission_policy.instances_user_has_permission_for(user, "publish")
@@ -143,6 +143,12 @@ The undocumented `get_pages_with_direct_explore_permission` and `get_explorable_
 
 The undocumented `users_with_page_permission` function in `wagtail.admin.auth` is also deprecated. It can be replaced with `PagePermissionPolicy().users_with_permission_for_instance(action, page, include_superusers)`.
 
+## `GroupPagePermission` now uses Django's `Permission` model
+
+The `GroupPagePermission` model that is responsible for assigning page permissions to groups now uses Django's `Permission` model instead of a custom string. This means that the `permission_type` `CharField` has been replaced with a `permission` `ForeignKey` to the `Permission` model.
+
+In addition to this, "edit" permissions now use the term `change` within the code. As a result, `GroupPagePermission`s that were previously recorded with `permission_type="edit"` are now recorded with a `Permission` object that has the `codename="change_page"` and a `content_type` that points to the `Page` model. Any permission checks that are done using `PagePermissionPolicy` should also use `change` instead of `edit`.
+
 ### The default ordering of Group Editing Permissions models has changed
 
 The ordering for "Object permissions" and "Other permissions" now follows a predictable order equivalent do Django's default `Model` ordering.