From 44e5beb4812a1a980e800a56b8218d34b22598d7 Mon Sep 17 00:00:00 2001
From: Matt Westcott <matt@west.co.tt>
Date: Fri, 28 Sep 2018 22:41:01 +0100
Subject: [PATCH] Release / deprecation notes for #4777

---
 CHANGELOG.txt         |  1 +
 docs/releases/2.3.rst | 42 ++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 43 insertions(+)

diff --git a/CHANGELOG.txt b/CHANGELOG.txt
index a25bb183d..567746c01 100644
--- a/CHANGELOG.txt
+++ b/CHANGELOG.txt
@@ -20,6 +20,7 @@ Changelog
  * Fix: Restored localisation in date/time pickers (David Moore, Thibaud Colas)
  * Fix: Tag input field no longer treats 'б' on Russian keyboards as a comma (Michael Borisov)
  * Fix: Disabled autocomplete dropdowns on date/time chooser fields (Janneke Janssen)
+ * Fix: Split up `wagtail.admin.forms` to make it less prone to circular imports (Matt Westcott)
 
 
 2.2.2 (29.08.2018)
diff --git a/docs/releases/2.3.rst b/docs/releases/2.3.rst
index a5d2eca26..eb7e181f5 100644
--- a/docs/releases/2.3.rst
+++ b/docs/releases/2.3.rst
@@ -43,6 +43,48 @@ Bug fixes
  * Restored localisation in date/time pickers (David Moore, Thibaud Colas)
  * Tag input field no longer treats 'б' on Russian keyboards as a comma (Michael Borisov)
  * Disabled autocomplete dropdowns on date/time chooser fields (Janneke Janssen)
+ * Split up ``wagtail.admin.forms`` to make it less prone to circular imports (Matt Westcott)
 
 Upgrade considerations
 ======================
+
+``wagtail.admin.forms`` reorganised
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``wagtail.admin.forms`` module has been split up into submodules to make it less prone to producing circular imports, particularly when a custom user model is in use. The following (undocumented) definitions have now been moved to new locations:
+
++----------------------------------------------+---------------------------------------+
+| Definition                                   | New location                          |
++==============================================+=======================================+
+| LoginForm                                    | wagtail.admin.forms.auth              |
++----------------------------------------------+---------------------------------------+
+| PasswordResetForm                            | wagtail.admin.forms.auth              |
++----------------------------------------------+---------------------------------------+
+| URLOrAbsolutePathValidator                   | wagtail.admin.forms.choosers          |
++----------------------------------------------+---------------------------------------+
+| URLOrAbsolutePathField                       | wagtail.admin.forms.choosers          |
++----------------------------------------------+---------------------------------------+
+| ExternalLinkChooserForm                      | wagtail.admin.forms.choosers          |
++----------------------------------------------+---------------------------------------+
+| EmailLinkChooserForm                         | wagtail.admin.forms.choosers          |
++----------------------------------------------+---------------------------------------+
+| CollectionViewRestrictionForm                | wagtail.admin.forms.collections       |
++----------------------------------------------+---------------------------------------+
+| CollectionForm                               | wagtail.admin.forms.collections       |
++----------------------------------------------+---------------------------------------+
+| BaseCollectionMemberForm                     | wagtail.admin.forms.collections       |
++----------------------------------------------+---------------------------------------+
+| BaseGroupCollectionMemberPermissionFormSet   | wagtail.admin.forms.collections       |
++----------------------------------------------+---------------------------------------+
+| collection_member_permission_formset_factory | wagtail.admin.forms.collections       |
++----------------------------------------------+---------------------------------------+
+| CopyForm                                     | wagtail.admin.forms.pages             |
++----------------------------------------------+---------------------------------------+
+| PageViewRestrictionForm                      | wagtail.admin.forms.pages             |
++----------------------------------------------+---------------------------------------+
+| SearchForm                                   | wagtail.admin.forms.search            |
++----------------------------------------------+---------------------------------------+
+| BaseViewRestrictionForm                      | wagtail.admin.forms.view_restrictions |
++----------------------------------------------+---------------------------------------+
+
+The following definitions remain in ``wagtail.admin.forms``: ``FORM_FIELD_OVERRIDES``, ``DIRECT_FORM_FIELD_OVERRIDES``, ``formfield_for_dbfield``, ``WagtailAdminModelFormMetaclass``, ``WagtailAdminModelForm`` and ``WagtailAdminPageForm``.