From d88ee0c5954cfbe577fb587c41d110a2fb397166 Mon Sep 17 00:00:00 2001 From: Sage Abdullah Date: Tue, 1 Aug 2023 12:33:23 +0100 Subject: [PATCH] Group 5.1 upgrade considerations by impact --- docs/releases/5.1.md | 232 ++++++++++++++++++++++--------------------- 1 file changed, 118 insertions(+), 114 deletions(-) diff --git a/docs/releases/5.1.md b/docs/releases/5.1.md index a96778cf48..284f9f7d26 100644 --- a/docs/releases/5.1.md +++ b/docs/releases/5.1.md @@ -182,7 +182,95 @@ we have made a number of improvements to snippets as part of [RFC 85: Snippets p * Upgrade documentation theme `sphinx_wagtail_theme` to v6.1.1 which includes multiple styling fixes and always visible code copy buttons (LB (Ben) Johnston) * Don't update the reference index while deleting it (Andy Chosak) -## Upgrade considerations +## Upgrade considerations - changes affecting all projects + +### `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 deprecated and 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`. + +If you have any fixtures for the `GroupPagePermission` model, you will need to update them to use the new `Permission` model. For example, if you have a fixture that looks like this: + +```json +{ + "pk": 11, + "model": "wagtailcore.grouppagepermission", + "fields": { + "group": ["Event moderators"], + "page": 12, + "permission_type": "edit" + } +} +``` + +Update it to use a natural key for the `permission` field instead of the `permission_type` field: + +```json +{ + "pk": 11, + "model": "wagtailcore.grouppagepermission", + "fields": { + "group": ["Event moderators"], + "page": 12, + "permission": ["change_page", "wagtailcore", "page"] + } +} +``` + +If you have any code that creates `GroupPagePermission` objects, you will need to update it to use the `Permission` model instead of the `permission_type` string. For example, if you have code that looks like this: + +```python +from wagtail.models import GroupPagePermission + +permission = GroupPagePermission(group=group, page=page, permission_type="edit") +permission.save() +``` + +Update it to use the `Permission` model instead: + +```python +from django.contrib.auth.models import Permission +from wagtail.models import GroupPagePermission + +permission = GroupPagePermission( + group=group, + page=page, + permission=Permission.objects.get(content_type__app_label="wagtailcore", codename="change_page"), +) +permission.save() +``` + +During the deprecation period, the `permission_type` field will still be available on the `GroupPagePermission` model and is used to automatically populate empty `permission` field as part of a system check. The `permission_type` field will be removed in Wagtail 6.0. + +### The default ordering of Group Editing Permissions models has changed + +The ordering for "Object permissions" and "Other permissions" now follows a predictable order equivalent to Django's default `Model` ordering. +This will be different to the previous ordering which never intentionally implemented. + +The default ordering is now `["content_type__app_label", "content_type__model"]`, which can now be customised [](customising_group_views_permissions_order). + +### JSON-timestamps stored in `ModelLogEntry` and `PageLogEntry` are now ISO-formatted and UTC + +Previously, timestamps stored in the "data"-`JSONField` of `ModelLogEntry` and `PageLogEntry` have used the custom python format `%d %b %Y %H:%M`. Additionally, the `"go_live_at"` timestamp had been stored with the configured local timezone, instead of UTC. + +This has now been fixed, all timestamps are now stored as UTC, and because the "data"-`JSONField` now uses Django's `DjangoJSONEncoder`, those `datetime` objects are now automatically converted to the ISO format. This release contains a new migration `0088_fix_log_entry_json_timestamps` which converts all existing timestamps used by Wagtail to the new format. + +If you've developed your own subclasses of `ModelLogEntry`, `PageLogEntry` or `BaseLogEntry`, or used those existing models to create custom log entries, and you've stored timestamps similarly to Wagtail's old implementation (using `strftime("%d %b %Y %H:%M")`). You may want to adapt the storage of those timestamps to a consistent format too. + +There are probably three places in your code, which have to be changed: + +1. Creation: Instead of using `strftime("%d %b %Y %H:%M")`, you can now store the datetime directly in the "data" field. We've implemented a new helper `wagtail.utils.timestamps.ensure_utc()`, which ensures the correct timezone (UTC). +2. Display: To display the timestamp in the user's timezone and format with a `LogFormatter`, we've created utils to parse (`wagtail.utils.timestamps.parse_datetime_localized()`) and render (`wagtail.utils.timestamps.render_timestamp()`) those timestamps. Look at the existing formatters [here](https://github.com/wagtail/wagtail/blob/main/wagtail/wagtail_hooks.py). +3. Migration: You can use the code of the above migration ([source](https://github.com/wagtail/wagtail/blob/main/wagtail/migrations/0088_fix_log_entry_json_timestamps.py)) as a guideline to migrate your existing timestamps in the database. + +### Image Renditions are now cached by default + +Wagtail will try to use the cache called "renditions". If no such cache exists, it will fall back to using the default cache. +You can [configure the "renditions" cache](custom_image_renditions_cache) to use a different cache backend or to provide +additional configuration parameters. + +## Upgrade considerations - deprecation of old functionality ### Removed support for Python 3.7 @@ -253,72 +341,6 @@ 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 deprecated and 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`. - -If you have any fixtures for the `GroupPagePermission` model, you will need to update them to use the new `Permission` model. For example, if you have a fixture that looks like this: - -```json -{ - "pk": 11, - "model": "wagtailcore.grouppagepermission", - "fields": { - "group": ["Event moderators"], - "page": 12, - "permission_type": "edit" - } -} -``` - -Update it to use a natural key for the `permission` field instead of the `permission_type` field: - -```json -{ - "pk": 11, - "model": "wagtailcore.grouppagepermission", - "fields": { - "group": ["Event moderators"], - "page": 12, - "permission": ["change_page", "wagtailcore", "page"] - } -} -``` - -If you have any code that creates `GroupPagePermission` objects, you will need to update it to use the `Permission` model instead of the `permission_type` string. For example, if you have code that looks like this: - -```python -from wagtail.models import GroupPagePermission - -permission = GroupPagePermission(group=group, page=page, permission_type="edit") -permission.save() -``` - -Update it to use the `Permission` model instead: - -```python -from django.contrib.auth.models import Permission -from wagtail.models import GroupPagePermission - -permission = GroupPagePermission( - group=group, - page=page, - permission=Permission.objects.get(content_type__app_label="wagtailcore", codename="change_page"), -) -permission.save() -``` - -During the deprecation period, the `permission_type` field will still be available on the `GroupPagePermission` model and is used to automatically populate empty `permission` field as part of a system check. The `permission_type` field will be removed in Wagtail 6.0. - -### The default ordering of Group Editing Permissions models has changed - -The ordering for "Object permissions" and "Other permissions" now follows a predictable order equivalent to Django's default `Model` ordering. -This will be different to the previous ordering which never intentionally implemented. - -The default ordering is now `["content_type__app_label", "content_type__model"]`, which can now be customised [](customising_group_views_permissions_order). - ### Shared include `wagtailadmin/shared/last_updated.html` is no longer available The undocumented shared include `wagtailadmin/shared/last_updated.html` is no longer available as it used the legacy Bootstrap tooltips and was not accessible. If you need to achieve a similar output, an element that shows a simple date with a tooltip for the full date, use the `human_readable_date` template tag instead. @@ -356,6 +378,8 @@ The documented include `"wagtailadmin/shared/field_as_li.html"` will be removed ``` +## Upgrade considerations - changes affecting Wagtail customisations + ### Tag (Tagit) field usage now relies on data attributes The `AdminTagWidget` widget has now been migrated to a Stimulus controller, if using this widget in Python, no changes are needed to adopt the new approach. @@ -389,53 +413,6 @@ The global util will be removed in a future release. It is recommended that the Note: The `data-w-tag-options-value` is a JSON object serialised into string. Django's HTML escaping will handle it automatically when you use the `AdminTagWidget`, but if you are manually writing the attributes, be sure to use quotation marks correctly. -### Image Renditions are now cached by default - -Wagtail will try to use the cache called "renditions". If no such cache exists, it will fall back to using the default cache. -You can [configure the "renditions" cache](custom_image_renditions_cache) to use a different cache backend or to provide -additional configuration parameters. - -### Tooltips now rely on new data attributes - -The undocumented Bootstrap jQuery tooltip widget is no longer in use, you will need to update any HTML that is using these attributes to the new syntax. - -```html - -Label - -Label -``` - -### Dialog hide/show custom events name change - -The undocumented client-side Custom Event handling for dialog showing & hiding will change in a future release. - -| Action | Old event | New event | -| ------ | -------------- | --------------- | -| Show | `wagtail:show` | `w-dialog:show` | -| Hide | `wagtail:hide` | `w-dialog:hide` | - -Additionally, two new events will be dispatched when the dialog visibility changes. - -| Action | Event name | -| ------ | ----------------- | -| Show | `w-dialog:shown` | -| Hide | `w-dialog:hidden` | - -### JSON-timestamps stored in `ModelLogEntry` and `PageLogEntry` are now ISO-formatted and UTC - -Previously, timestamps stored in the "data"-`JSONField` of `ModelLogEntry` and `PageLogEntry` have used the custom python format `%d %b %Y %H:%M`. Additionally, the `"go_live_at"` timestamp had been stored with the configured local timezone, instead of UTC. - -This has now been fixed, all timestamps are now stored as UTC, and because the "data"-`JSONField` now uses Django's `DjangoJSONEncoder`, those `datetime` objects are now automatically converted to the ISO format. This release contains a new migration `0088_fix_log_entry_json_timestamps` which converts all existing timestamps used by Wagtail to the new format. - -If you've developed your own subclasses of `ModelLogEntry`, `PageLogEntry` or `BaseLogEntry`, or used those existing models to create custom log entries, and you've stored timestamps similarly to Wagtail's old implementation (using `strftime("%d %b %Y %H:%M")`). You may want to adapt the storage of those timestamps to a consistent format too. - -There are probably three places in your code, which have to be changed: - -1. Creation: Instead of using `strftime("%d %b %Y %H:%M")`, you can now store the datetime directly in the "data" field. We've implemented a new helper `wagtail.utils.timestamps.ensure_utc()`, which ensures the correct timezone (UTC). -2. Display: To display the timestamp in the user's timezone and format with a `LogFormatter`, we've created utils to parse (`wagtail.utils.timestamps.parse_datetime_localized()`) and render (`wagtail.utils.timestamps.render_timestamp()`) those timestamps. Look at the existing formatters [here](https://github.com/wagtail/wagtail/blob/main/wagtail/wagtail_hooks.py). -3. Migration: You can use the code of the above migration ([source](https://github.com/wagtail/wagtail/blob/main/wagtail/migrations/0088_fix_log_entry_json_timestamps.py)) as a guideline to migrate your existing timestamps in the database. - ### Header searching now relies on data attributes Previously the header search relied on inline scripts and a `window.headerSearch` global to activate the behaviour. This has now changed to a data attributes approach and the window global usage will be removed in a future major release. @@ -511,3 +488,30 @@ Alternatively, if you have customisations that manually declare or override `win
``` + +### Tooltips now rely on new data attributes + +The undocumented Bootstrap jQuery tooltip widget is no longer in use, you will need to update any HTML that is using these attributes to the new syntax. + +```html + +Label + +Label +``` + +### Dialog hide/show custom events name change + +The undocumented client-side Custom Event handling for dialog showing & hiding will change in a future release. + +| Action | Old event | New event | +| ------ | -------------- | --------------- | +| Show | `wagtail:show` | `w-dialog:show` | +| Hide | `wagtail:hide` | `w-dialog:hide` | + +Additionally, two new events will be dispatched when the dialog visibility changes. + +| Action | Event name | +| ------ | ----------------- | +| Show | `w-dialog:shown` | +| Hide | `w-dialog:hidden` |