Release note for #9935 in 4.1.x

CHANGELOG.txt

@@ -178,6 +178,7 @@ Changelog
  * Fix: Ensure edit form is displayed as unlocked immediately after cancelling a workflow (Sage Abdullah)
  * Fix: Prevent `latest_revision` pointer from being copied over when copying translatable snippets for translation (Sage Abdullah)
  * Docs: Document potential data loss for BaseLogEntry migration in 3.0 (Sage Abdullah)
+ * Docs: Add documentation for the reference index mechanism (Daniel Kirkham)
 
 
 4.1.1 (11.11.2022)

docs/advanced_topics/reference_index.md

@@ -1,3 +1,4 @@
+(managing_the_reference_index)=
 # Managing the Reference Index
 
 Wagtail maintains a reference index, which records references between objects whenever those objects are saved. The index allows Wagtail to efficiently report the usage of images, documents and snippets within pages, including within StreamField and rich text fields.

docs/releases/4.1.2.md

@@ -30,3 +30,4 @@ depth: 1
 ### Documentation
 
  * Document potential data loss for BaseLogEntry migration in 3.0 (Sage Abdullah)
+ * Add documentation for the reference index mechanism (Daniel Kirkham)

docs/releases/4.1.md

@@ -45,7 +45,7 @@ Snippet models that inherit from `DraftStateMixin` can now be assigned go-live a
 
 Images, documents and snippets now provide a usage report, listing the places where references to those objects appear. This report is powered by a new `ReferenceIndex` model which records cross-references between objects whenever those objects to save; this allows it to work more efficiently than the old report available through the `WAGTAIL_USAGE_COUNT_ENABLED` setting, as well as handling references within StreamField and rich text fields.
 
-Note that on first upgrading to Wagtail 4.1, you will need to run the `rebuild_references_index` management command to populate the references table and ensure that reference counts are displayed accurately.
+Note that on first upgrading to Wagtail 4.1, you will need to run the `rebuild_references_index` management command to populate the references table and ensure that reference counts are displayed accurately. By default, references are tracked for all models in the project, including ones not managed through Wagtail - to disable this for specific models, see [](managing_the_reference_index).
 
 This feature was developed by Karl Hobley and Matt Westcott.
 
@@ -143,7 +143,7 @@ There are multiple improvements to the documentation theme this release, here ar
 
 ### `rebuild_references_index` management command
 
-After upgrading, you will need to run `./manage.py rebuild_references_index` in order to populate the references table and ensure that usage counts for images, documents and snippets are displayed accurately.
+After upgrading, you will need to run `./manage.py rebuild_references_index` in order to populate the references table and ensure that usage counts for images, documents and snippets are displayed accurately. By default, references are tracked for all models in the project, including ones not managed through Wagtail - to disable this for specific models, see [](managing_the_reference_index).
 
 ### Recommend `WagtailPageTestCase` in place of `WagtailPageTests`