From 77d783b397d023d2d47ddc8157634e96d3995a1d Mon Sep 17 00:00:00 2001
From: Tibor Leupold <tibor@lpld.io>
Date: Sun, 10 Mar 2024 10:02:02 -0700
Subject: [PATCH] Add note about StreamField validation happening on the form

---
 CHANGELOG.txt                                  | 1 +
 docs/advanced_topics/streamfield_validation.md | 8 ++++++++
 docs/releases/6.1.md                           | 1 +
 3 files changed, 10 insertions(+)

diff --git a/CHANGELOG.txt b/CHANGELOG.txt
index b6c737d47da3..da7a59363bd3 100644
--- a/CHANGELOG.txt
+++ b/CHANGELOG.txt
@@ -37,6 +37,7 @@ Changelog
  * Docs: Update template components documentation to better explain the usage of the Laces library (Tibor Leupold)
  * Docs: Update Sphinx theme to `6.3.0` with a fix for the missing favicon (Sage Abdullah)
  * Docs: Document risk of XSS attacks on document upload (Matt Westcott, with thanks to Georgios Roumeliotis of TwelveSec for the original report)
+ * Docs: Add clarity to how custom StreamField validation works (Tibor Leupold)
  * Maintenance: Move RichText HTML whitelist parser to use the faster, built in `html.parser` (Jake Howard)
  * Maintenance: Remove duplicate 'path' in default_exclude_fields_in_copy (Ramchandra Shahi Thakuri)
  * Maintenance: Update unit tests to always use the faster, built in `html.parser` & remove `html5lib` dependency (Jake Howard)
diff --git a/docs/advanced_topics/streamfield_validation.md b/docs/advanced_topics/streamfield_validation.md
index c19a2829321b..e0c45938609e 100644
--- a/docs/advanced_topics/streamfield_validation.md
+++ b/docs/advanced_topics/streamfield_validation.md
@@ -21,6 +21,14 @@ class LinkBlock(StructBlock):
         return result
 ```
 
+```{note}
+The validation of the blocks in the `StreamField` happens through the form field (`wagtail.blocks.base.BlockField`), not the model field (`wagtail.fields.StreamField`).
+
+This means that calling validation methods on your page instance (such as `my_page.full_clean()`) won't catch invalid blocks in the `StreamField` data.
+
+This should only be relevant when the data in the `StreamField` is added programmatically, through other paths than the form field.
+```
+
 ## Controlling where error messages are rendered
 
 In the above example, an exception of type `ValidationError` is raised, which causes the error to be attached and rendered against the StructBlock as a whole. For more control over where the error appears, the exception class `wagtail.blocks.StructBlockValidationError` can be raised instead. The constructor for this class accepts the following arguments:
diff --git a/docs/releases/6.1.md b/docs/releases/6.1.md
index d60985e913f2..24a94f8c7ae9 100644
--- a/docs/releases/6.1.md
+++ b/docs/releases/6.1.md
@@ -55,6 +55,7 @@ depth: 1
  * Update [template components](creating_template_components) documentation to better explain the usage of the Laces library (Tibor Leupold)
  * Update Sphinx theme to `6.3.0` with a fix for the missing favicon (Sage Abdullah)
  * Document risk of XSS attacks on document upload (Matt Westcott, with thanks to Georgios Roumeliotis of TwelveSec for the original report)
+ * Add clarity to how custom [StreamField validation](streamfield_validation) works (Tibor Leupold)
 
 
 ### Maintenance