Document the ability to migrate from ImageChooserBlock to ImageBlock (#12518)

docs/reference/streamfield/blocks.md

@@ -347,10 +347,18 @@ All block definitions accept the following optional keyword arguments:
 .. autoclass:: wagtail.images.blocks.ImageBlock
     :show-inheritance:
 
-    An accessibility-focused control to allow the editor to select an existing image, or upload a new one. This has provision for adding alt text, indicating whether images are purely decorative, and is the Wagtail-recommended approach to uploading images. The following additional keyword argument is accepted:
+    An accessibility-focused control to allow the editor to select an existing image, or upload a new one. This has provision for adding alt text and indicating whether images are purely decorative, and is the Wagtail-recommended approach to uploading images. The following additional keyword argument is accepted:
 
     :param required: If true (the default), the field cannot be left blank.
 
+    ``ImageBlock`` incorporates backwards compatibility with ``ImageChooserBlock``. A block initially defined as ``ImageChooserBlock`` can be directly replaced with ``ImageBlock`` - existing data created with ``ImageChooserBlock`` will be handled automatically and changed to ``ImageBlock``'s data format when the field is resaved.
+```
+
+```{versionadded} 6.3
+The `ImageBlock` block type was added. Blocks previously defined as `ImageChooserBlock` can be directly replaced with `ImageBlock` to benefit from the alt text support, with no data migration or template changes required.
+```
+
+```{eval-rst}
 .. autoclass:: wagtail.images.blocks.ImageChooserBlock
     :show-inheritance:
 

docs/releases/6.3.md

@@ -23,7 +23,7 @@ This release adds formal support for Django 5.1.
 
 ### `ImageBlock` with alt text support
 
-This release introduces a new block type [`ImageBlock`](streamfield_imageblock), which improves upon `ImageChooserBlock` by allowing editors to specify alt text tailored to the context in which the image is used. This can be used as a direct replacement for `ImageChooserBlock`, and is the new recommended block type for all images that are not purely decorative. This feature was developed by Chiemezuo Akujobi as part of the Google Summer of Code program with mentoring support from Storm Heg, Saptak Sengupta, Thibaud Colas and Matt Westcott.
+This release introduces a new block type [`ImageBlock`](streamfield_imageblock), which improves upon `ImageChooserBlock` by allowing editors to specify alt text tailored to the context in which the image is used. This is the new recommended block type for all images that are not purely decorative, and existing instances of `ImageChooserBlock` can be directly replaced with `ImageBlock` (with no data migration or template changes required) to benefit from contextual alt text. This feature was developed by Chiemezuo Akujobi as part of the Google Summer of Code program with mentoring support from Storm Heg, Saptak Sengupta, Thibaud Colas and Matt Westcott.
 
 ### Incremental dashboard enhancements