Improve migration guide for codecs (#3273)

dstansby · web-flow · commit fd5425b954ad · 2025-07-22T11:56:18.000+01:00
diff --git a/changes/3273.doc.rst b/changes/3273.doc.rst
@@ -0,0 +1 @@
+Add a section on codecs to the migration guide.
diff --git a/docs/user-guide/v3_migration.rst b/docs/user-guide/v3_migration.rst
@@ -58,7 +58,7 @@ the following actions in order:
      vendor the parts of the specific modules that you need.
 
      * ``zarr.attrs`` has gone, with no replacement
-     * ``zarr.codecs`` has gone, use ``numcodecs`` instead
+     * ``zarr.codecs`` has changed, see "Codecs" section below for more information
      * ``zarr.context`` has gone, with no replacement
      * ``zarr.core`` remains but should be considered private API
      * ``zarr.hierarchy`` has gone, with no replacement (use ``zarr.Group`` inplace of ``zarr.hierarchy.Group``)
@@ -178,6 +178,18 @@ If you are interested in developing a custom store that targets these backends,
 :ref:`developing custom stores <user-guide-custom-stores>` or open an
 `issue <https://github.com/zarr-developers/zarr-python/issues>`_ to discuss your use case.
 
+
+Codecs
+~~~~~~
+Codecs defined in ``numcodecs`` (and also imported into the ``zarr.codecs`` namespace in Zarr-Python 2)
+should still be used when creating Zarr format 2 arrays.
+
+Codecs for creating Zarr format 3 arrays are available in two locations:
+
+- `zarr.codecs` contains Zarr format 3 codecs that are defined in the `codecs section of the Zarr format 3 specification <https://zarr-specs.readthedocs.io/en/latest/v3/codecs/index.html>`_.
+- `numcodecs.zarr3` contains codecs from ``numcodecs`` that can be used to create Zarr format 3 arrays, but are not necessarily part of the Zarr format 3 specification.
+
+
 Dependencies
 ~~~~~~~~~~~~
 

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+Add a section on codecs to the migration guide.`