Document the vary_fields property for custom image filters

CHANGELOG.txt

@@ -49,6 +49,7 @@ Changelog
  * Docs: Add note about `prefers-reduced-motion` to the accessibility documentation (Roel Koper)
  * Docs: Update deployment instructions for Fly.io (Jeroen de Vries)
  * Docs: Add better docs for generating URLs on creating admin views (Shlomo Markowitz)
+ * Docs: Document the `vary_fields` property for custom image filters (Daniel Kirkham)
  * Maintenance: Use `DjangoJSONEncoder` instead of custom `LazyStringEncoder` to serialize Draftail config (Sage Abdullah)
  * Maintenance: Refactor image chooser pagination to check `WAGTAILIMAGES_CHOOSER_PAGE_SIZE` at runtime (Matt Westcott)
  * Maintenance: Exclude the `client/scss` directory in Tailwind content config to speed up CSS compilation (Sage Abdullah)

docs/extending/custom_image_filters.md

@@ -36,3 +36,16 @@ Use the filter in a template, like so:
 
 {% image page.photo width-400 blur-7 %}
 ```
+
+If your custom image filter depends on fields within the `Image`, for instance those defining the focal point, add a `vary_fields` property listing those field names to the subclassed `FilterOperation`. This ensures that a new rendition is created whenever the focal point is changed:
+
+```python
+class BlurOutsideFocusPointOperation(FilterOperation):
+    vary_fields = (
+        "focal_point_width",
+        "focal_point_height",
+        "focal_point_x",
+        "focal_point_y",
+    )
+    # ...
+```

docs/releases/6.2.md

@@ -70,6 +70,7 @@ This feature was implemented by Albina Starykova, with support from the Wagtail
  * Add note about `prefers-reduced-motion` to the accessibility documentation (Roel Koper)
  * Update deployment instructions for Fly.io (Jeroen de Vries)
  * Add better docs for generating URLs on [creating admin views](../extending/admin_views.md) (Shlomo Markowitz)
+ * Document the `vary_fields` property for [custom image filters](custom_image_filters) (Daniel Kirkham)
 
 ### Maintenance