Deprecation note for #5128

docs/releases/2.5.rst

@@ -59,3 +59,36 @@ Upgrade considerations
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The internal ``EditHandler`` methods ``bind_to_model`` and ``bind_to_instance`` have been deprecated, in favour of a new combined ``bind_to`` method which accepts ``model``, ``instance``, ``request`` and ``form`` as optional keyword arguments. Any user code which calls ``EditHandler.bind_to_model(model)`` should be updated to use ``EditHandler.bind_to(model=model)`` instead; any user code which calls ``EditHandler.bind_to_instance(instance, request, form)`` should be updated to use ``EditHandler.bind_to(instance=instance, request=request, form=form)``.
+
+
+Changes to admin pagination helpers
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A number of changes have been made to pagination handling within the Wagtail admin; these are internal API changes, but may affect applications and third-party packages that add new paginated object listings, including chooser modals, to the admin. The ``paginate`` function in ``wagtail.utils.pagination`` has been deprecated in favour of the ``django.core.paginator.Paginator.get_page`` method introduced in Django 2.0 - a call such as:
+
+  .. code-block:: python
+
+    from wagtail.utils.pagination import paginate
+
+    paginator, page = paginate(request, object_list, per_page=25)
+
+should be replaced with:
+
+  .. code-block:: python
+
+    from django.core.paginator import Paginator
+
+    paginator = Paginator(object_list, per_page=25)
+    page = paginator.get_page(request.GET.get('p'))
+
+Additionally, the ``is_ajax`` flag on the template ``wagtailadmin/shared/pagination_nav.html`` has been deprecated in favour of a new template ``wagtailadmin/shared/ajax_pagination_nav.html``:
+
+  .. code-block:: html+django
+
+    {% include "wagtailadmin/shared/pagination_nav.html" with items=page_obj is_ajax=1 %}
+
+should become:
+
+  .. code-block:: html+django
+
+    {% include "wagtailadmin/shared/ajax_pagination_nav.html" with items=page_obj %}