kopia lustrzana https://github.com/wagtail/wagtail
Group 5.1 upgrade considerations by impact
Sage Abdullah
rodzic
e8a36191d2
commit
d88ee0c595
|
|
@ -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
|
|||
</li>
|
||||
```
|
||||
|
||||
## 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
|
||||
<!-- Old attributes: -->
|
||||
<span data-wagtail-tooltip="Tooltip content here">Label</span>
|
||||
<!-- New attributes: -->
|
||||
<span data-controller="w-tooltip" data-w-tooltip-content-value="Tooltip content here">Label</span>
|
||||
```
|
||||
|
||||
### 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
|
|||
</form>
|
||||
<div id="some-results"></div>
|
||||
```
|
||||
|
||||
### 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
|
||||
<!-- Old attributes: -->
|
||||
<span data-wagtail-tooltip="Tooltip content here">Label</span>
|
||||
<!-- New attributes: -->
|
||||
<span data-controller="w-tooltip" data-w-tooltip-content-value="Tooltip content here">Label</span>
|
||||
```
|
||||
|
||||
### 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` |
|
||||
|
|
|
|||
Ładowanie…
Reference in New Issue