From bd63fdf363508b3c0c77319dc3248b53650fba4c Mon Sep 17 00:00:00 2001
From: Davis Vann Bennett <davis.v.bennett@gmail.com>
Date: Thu, 12 Nov 2026 23:28:40 +0100
Subject: [PATCH 1/2] chore(zarr-metadata): build 0.8.0 changelog

Assisted-by: ClaudeCode:claude-opus-5-5
---
 packages/zarr-metadata/CHANGELOG.md           | 58 +++++++++++++++++++
 packages/zarr-metadata/changes/4621.bugfix.md |  1 -
 .../zarr-metadata/changes/4621.feature.md     |  1 -
 .../zarr-metadata/changes/4622.removal.md     |  1 -
 packages/zarr-metadata/changes/4627.misc.md   |  7 ---
 packages/zarr-metadata/changes/4628.bugfix.md | 10 ----
 .../zarr-metadata/changes/4628.feature.md     | 21 -------
 7 files changed, 58 insertions(+), 41 deletions(-)
 delete mode 100644 packages/zarr-metadata/changes/4621.bugfix.md
 delete mode 100644 packages/zarr-metadata/changes/4621.feature.md
 delete mode 100644 packages/zarr-metadata/changes/4622.removal.md
 delete mode 100644 packages/zarr-metadata/changes/4627.misc.md
 delete mode 100644 packages/zarr-metadata/changes/4628.bugfix.md
 delete mode 100644 packages/zarr-metadata/changes/4628.feature.md

diff --git a/packages/zarr-metadata/CHANGELOG.md b/packages/zarr-metadata/CHANGELOG.md
index e927a7c8fb..4c9e03ade0 100644
--- a/packages/zarr-metadata/CHANGELOG.md
+++ b/packages/zarr-metadata/CHANGELOG.md
@@ -2,6 +2,64 @@
 
 <!-- towncrier release notes start -->
 
+## 0.8.0 (2026-11-12)
+
+### Features
+
+- **Breaking:** `create_default` derives each member that depends on a member given, unless that member is given too. In v3, a `data_type` brings its default fill value and its array -> bytes codec: `vlen-utf8` for `string`, `vlen-bytes` for `bytes` and `variable_length_bytes`, and `bytes` for any other data type. So `ZarrV3ArrayMetadata.create_default(data_type="bool")` and `create_default(data_type="string")` now work. In v2, a `dtype` brings its default fill value: `false` for `|b1`, `""` for `|S` and `<U`, and null bytes for `|V` and structs, where these got `null`. In both formats, a time data type now gets `"NaT"` where it got `0` (the epoch), and a float gets `0.0` where it got `0`, which is the same value written another way. `|O`, whose values may be of any type, has no default and gets `null` where it got `0`, and a v3 data type that nothing in scope claims needs a `fill_value`. A member given with a problem derives nothing, so its problem is the only one reported. When the document has a problem, the error notes each member `create_default` filled in. The defaults come from a new `fill_value_default` on a data type definition, which every data type this package defines declares, with the values zarr-python uses: zero, `false`, the empty string, null bytes, and not-a-time. `zarr_metadata.definition` exports `ConstantFillValue`, for a default that does not depend on the configuration, and `default_fill_value(data_type)`. The codec comes from a new `array_bytes_codec_default` on a v3 data type definition, read with `zarr_metadata.v3.definition.default_array_bytes_codec(data_type)`, so an extension data type whose values vary in size can declare its own. ([#4621](https://github.com/zarr-developers/zarr-python/pull/4621))
+
+- **Breaking:** a v3 codec is defined with the class of its kind,
+    `ArrayArrayCodecDefinition`, `ArrayBytesCodecDefinition` or
+    `BytesBytesCodecDefinition`, instead of `CodecDefinition(kind=...)`. The kind
+    is now the class's `kind` property, and `CodecDefinition` is their abstract
+    base, which a scope and `resolve` still use to name the kind. A codec that
+    receives an array, an `ArrayCodecDefinition`, has `chunk_rules` and
+    `pipelines`, an array -> array codec also has `transition`, and a bytes ->
+    bytes codec, which receives bytes, has none of them, so building one with any
+    of them is a `TypeError` from the class itself.
+
+    A v3 data type definition declares what kind of numbers its values are with
+    `number_class`, a `NumberClass`: `"integral"`, `"floating_point"`,
+    `"complex"` or `"non_numeric"`. `cast_value` and `scale_offset` read it to
+    decide which data types they accept, where each kept a list of data type
+    names, so a data type defined elsewhere is judged by what it declares: both
+    codecs refuse one that declares complex or non-numeric values, and
+    `cast_value` refuses to `wrap` to one that declares floating-point values. A
+    data type that declares no number class is accepted by both, as before. A data
+    type defined elsewhere under one of the float names the `cast_value` spec
+    lists, such as `bfloat16`, was refused as a `wrap` target by its name, and is
+    now refused once it declares `"floating_point"`. ([#4628](https://github.com/zarr-developers/zarr-python/pull/4628))
+
+### Bugfixes
+
+- `ZarrV2ArrayMetadata.create_default(shape=...)` derives a chunk length of 1 for a dimension of length 0, as the v3 model does, where it wrote 0, which zarr-python repairs to 1 on read. ([#4621](https://github.com/zarr-developers/zarr-python/pull/4621))
+
+- **Breaking:** `cast_value` and `scale_offset` refuse the data types their
+    specs do not list. Each spec names the integer and floating-point types as
+    "the following data types defined in this repository" that it supports, and
+    that repository also defines the numpy time types and the complex types. So
+    both codecs now refuse `numpy.datetime64` and `numpy.timedelta64`, and
+    `cast_value` refuses them as the data type it casts to, and `scale_offset`
+    now refuses `complex64` and `complex128`. All of these were accepted. The time
+    types' own spec says they are "compatible with any codec that supports arrays
+    of signed 64-bit integers", which the two codecs' specs do not bear out.
+    `zarr_metadata.testing.strategies` no longer draws these combinations. ([#4628](https://github.com/zarr-developers/zarr-python/pull/4628))
+
+### Deprecations and Removals
+
+- **Breaking:** The models' `update` method is now `replace`, the name Python gives a method that returns a changed copy of an immutable value, as `str.replace`, `datetime.replace` and `dataclasses.replace` do: `update`, as `dict.update` uses it, says that the object itself changes. It takes the same members and returns a new model, read in the model's own scope, as before. Each model also defines `__replace__`, so `copy.replace(model, attributes={"a": 1})` works on Python 3.13 and later. To migrate, rename each `model.update(...)` call to `model.replace(...)`. The `...Update` TypedDicts that type its members keep their names. ([#4622](https://github.com/zarr-developers/zarr-python/pull/4622))
+
+### Misc
+
+- The types of every extension (each codec's, data type's, chunk grid's and
+    chunk key encoding's name constants, `Literal` types, configuration and object
+    `TypedDict`s and metadata aliases, in both formats) now live in private modules
+    that hold types only and import no definition. A definition of one kind can
+    therefore import the types of another kind at run time, as a data type that
+    names its default codec does. Every name keeps its public import paths, since
+    each extension's module re-exports its types. ([#4627](https://github.com/zarr-developers/zarr-python/pull/4627))
+
+
 ## 0.7.0 (2026-11-11)
 
 ### Features
diff --git a/packages/zarr-metadata/changes/4621.bugfix.md b/packages/zarr-metadata/changes/4621.bugfix.md
deleted file mode 100644
index 5438494091..0000000000
--- a/packages/zarr-metadata/changes/4621.bugfix.md
+++ /dev/null
@@ -1 +0,0 @@
-`ZarrV2ArrayMetadata.create_default(shape=...)` derives a chunk length of 1 for a dimension of length 0, as the v3 model does, where it wrote 0, which zarr-python repairs to 1 on read.
diff --git a/packages/zarr-metadata/changes/4621.feature.md b/packages/zarr-metadata/changes/4621.feature.md
deleted file mode 100644
index 70d6aae191..0000000000
--- a/packages/zarr-metadata/changes/4621.feature.md
+++ /dev/null
@@ -1 +0,0 @@
-**Breaking:** `create_default` derives each member that depends on a member given, unless that member is given too. In v3, a `data_type` brings its default fill value and its array -> bytes codec: `vlen-utf8` for `string`, `vlen-bytes` for `bytes` and `variable_length_bytes`, and `bytes` for any other data type. So `ZarrV3ArrayMetadata.create_default(data_type="bool")` and `create_default(data_type="string")` now work. In v2, a `dtype` brings its default fill value: `false` for `|b1`, `""` for `|S` and `<U`, and null bytes for `|V` and structs, where these got `null`. In both formats, a time data type now gets `"NaT"` where it got `0` (the epoch), and a float gets `0.0` where it got `0`, which is the same value written another way. `|O`, whose values may be of any type, has no default and gets `null` where it got `0`, and a v3 data type that nothing in scope claims needs a `fill_value`. A member given with a problem derives nothing, so its problem is the only one reported. When the document has a problem, the error notes each member `create_default` filled in. The defaults come from a new `fill_value_default` on a data type definition, which every data type this package defines declares, with the values zarr-python uses: zero, `false`, the empty string, null bytes, and not-a-time. `zarr_metadata.definition` exports `ConstantFillValue`, for a default that does not depend on the configuration, and `default_fill_value(data_type)`. The codec comes from a new `array_bytes_codec_default` on a v3 data type definition, read with `zarr_metadata.v3.definition.default_array_bytes_codec(data_type)`, so an extension data type whose values vary in size can declare its own.
diff --git a/packages/zarr-metadata/changes/4622.removal.md b/packages/zarr-metadata/changes/4622.removal.md
deleted file mode 100644
index 7fc6cf40c5..0000000000
--- a/packages/zarr-metadata/changes/4622.removal.md
+++ /dev/null
@@ -1 +0,0 @@
-**Breaking:** The models' `update` method is now `replace`, the name Python gives a method that returns a changed copy of an immutable value, as `str.replace`, `datetime.replace` and `dataclasses.replace` do: `update`, as `dict.update` uses it, says that the object itself changes. It takes the same members and returns a new model, read in the model's own scope, as before. Each model also defines `__replace__`, so `copy.replace(model, attributes={"a": 1})` works on Python 3.13 and later. To migrate, rename each `model.update(...)` call to `model.replace(...)`. The `...Update` TypedDicts that type its members keep their names.
diff --git a/packages/zarr-metadata/changes/4627.misc.md b/packages/zarr-metadata/changes/4627.misc.md
deleted file mode 100644
index 46508e8d26..0000000000
--- a/packages/zarr-metadata/changes/4627.misc.md
+++ /dev/null
@@ -1,7 +0,0 @@
-The types of every extension (each codec's, data type's, chunk grid's and
-chunk key encoding's name constants, `Literal` types, configuration and object
-`TypedDict`s and metadata aliases, in both formats) now live in private modules
-that hold types only and import no definition. A definition of one kind can
-therefore import the types of another kind at run time, as a data type that
-names its default codec does. Every name keeps its public import paths, since
-each extension's module re-exports its types.
diff --git a/packages/zarr-metadata/changes/4628.bugfix.md b/packages/zarr-metadata/changes/4628.bugfix.md
deleted file mode 100644
index 07af0924ff..0000000000
--- a/packages/zarr-metadata/changes/4628.bugfix.md
+++ /dev/null
@@ -1,10 +0,0 @@
-**Breaking:** `cast_value` and `scale_offset` refuse the data types their
-specs do not list. Each spec names the integer and floating-point types as
-"the following data types defined in this repository" that it supports, and
-that repository also defines the numpy time types and the complex types. So
-both codecs now refuse `numpy.datetime64` and `numpy.timedelta64`, and
-`cast_value` refuses them as the data type it casts to, and `scale_offset`
-now refuses `complex64` and `complex128`. All of these were accepted. The time
-types' own spec says they are "compatible with any codec that supports arrays
-of signed 64-bit integers", which the two codecs' specs do not bear out.
-`zarr_metadata.testing.strategies` no longer draws these combinations.
diff --git a/packages/zarr-metadata/changes/4628.feature.md b/packages/zarr-metadata/changes/4628.feature.md
deleted file mode 100644
index 0765e5b880..0000000000
--- a/packages/zarr-metadata/changes/4628.feature.md
+++ /dev/null
@@ -1,21 +0,0 @@
-**Breaking:** a v3 codec is defined with the class of its kind,
-`ArrayArrayCodecDefinition`, `ArrayBytesCodecDefinition` or
-`BytesBytesCodecDefinition`, instead of `CodecDefinition(kind=...)`. The kind
-is now the class's `kind` property, and `CodecDefinition` is their abstract
-base, which a scope and `resolve` still use to name the kind. A codec that
-receives an array, an `ArrayCodecDefinition`, has `chunk_rules` and
-`pipelines`, an array -> array codec also has `transition`, and a bytes ->
-bytes codec, which receives bytes, has none of them, so building one with any
-of them is a `TypeError` from the class itself.
-
-A v3 data type definition declares what kind of numbers its values are with
-`number_class`, a `NumberClass`: `"integral"`, `"floating_point"`,
-`"complex"` or `"non_numeric"`. `cast_value` and `scale_offset` read it to
-decide which data types they accept, where each kept a list of data type
-names, so a data type defined elsewhere is judged by what it declares: both
-codecs refuse one that declares complex or non-numeric values, and
-`cast_value` refuses to `wrap` to one that declares floating-point values. A
-data type that declares no number class is accepted by both, as before. A data
-type defined elsewhere under one of the float names the `cast_value` spec
-lists, such as `bfloat16`, was refused as a `wrap` target by its name, and is
-now refused once it declares `"floating_point"`.

From 52cd9c9644c294edc31233dfc87d53cdfca4e239 Mon Sep 17 00:00:00 2001
From: Davis Vann Bennett <davis.v.bennett@gmail.com>
Date: Thu, 12 Nov 2026 23:43:34 +0100
Subject: [PATCH 2/2] docs(zarr-metadata): condense the long 0.8.0 release
 notes

Shortens the #4621 and #4628 feature entries and the #4628 bugfix entry
from 254, 216 and 111 words to 132, 140 and 43. The dropped detail, such
as the float 0.0 spelling, how create_default reports a member given
with a problem, the bfloat16 example and the argument from the spec text
for refusing the time and complex types, stays in those pull requests.

Assisted-by: ClaudeCode:claude-opus-5-5
---
 packages/zarr-metadata/CHANGELOG.md | 39 +++++------------------------
 1 file changed, 6 insertions(+), 33 deletions(-)

diff --git a/packages/zarr-metadata/CHANGELOG.md b/packages/zarr-metadata/CHANGELOG.md
index 4c9e03ade0..af9f6a2e98 100644
--- a/packages/zarr-metadata/CHANGELOG.md
+++ b/packages/zarr-metadata/CHANGELOG.md
@@ -6,44 +6,17 @@
 
 ### Features
 
-- **Breaking:** `create_default` derives each member that depends on a member given, unless that member is given too. In v3, a `data_type` brings its default fill value and its array -> bytes codec: `vlen-utf8` for `string`, `vlen-bytes` for `bytes` and `variable_length_bytes`, and `bytes` for any other data type. So `ZarrV3ArrayMetadata.create_default(data_type="bool")` and `create_default(data_type="string")` now work. In v2, a `dtype` brings its default fill value: `false` for `|b1`, `""` for `|S` and `<U`, and null bytes for `|V` and structs, where these got `null`. In both formats, a time data type now gets `"NaT"` where it got `0` (the epoch), and a float gets `0.0` where it got `0`, which is the same value written another way. `|O`, whose values may be of any type, has no default and gets `null` where it got `0`, and a v3 data type that nothing in scope claims needs a `fill_value`. A member given with a problem derives nothing, so its problem is the only one reported. When the document has a problem, the error notes each member `create_default` filled in. The defaults come from a new `fill_value_default` on a data type definition, which every data type this package defines declares, with the values zarr-python uses: zero, `false`, the empty string, null bytes, and not-a-time. `zarr_metadata.definition` exports `ConstantFillValue`, for a default that does not depend on the configuration, and `default_fill_value(data_type)`. The codec comes from a new `array_bytes_codec_default` on a v3 data type definition, read with `zarr_metadata.v3.definition.default_array_bytes_codec(data_type)`, so an extension data type whose values vary in size can declare its own. ([#4621](https://github.com/zarr-developers/zarr-python/pull/4621))
-
-- **Breaking:** a v3 codec is defined with the class of its kind,
-    `ArrayArrayCodecDefinition`, `ArrayBytesCodecDefinition` or
-    `BytesBytesCodecDefinition`, instead of `CodecDefinition(kind=...)`. The kind
-    is now the class's `kind` property, and `CodecDefinition` is their abstract
-    base, which a scope and `resolve` still use to name the kind. A codec that
-    receives an array, an `ArrayCodecDefinition`, has `chunk_rules` and
-    `pipelines`, an array -> array codec also has `transition`, and a bytes ->
-    bytes codec, which receives bytes, has none of them, so building one with any
-    of them is a `TypeError` from the class itself.
-
-    A v3 data type definition declares what kind of numbers its values are with
-    `number_class`, a `NumberClass`: `"integral"`, `"floating_point"`,
-    `"complex"` or `"non_numeric"`. `cast_value` and `scale_offset` read it to
-    decide which data types they accept, where each kept a list of data type
-    names, so a data type defined elsewhere is judged by what it declares: both
-    codecs refuse one that declares complex or non-numeric values, and
-    `cast_value` refuses to `wrap` to one that declares floating-point values. A
-    data type that declares no number class is accepted by both, as before. A data
-    type defined elsewhere under one of the float names the `cast_value` spec
-    lists, such as `bfloat16`, was refused as a `wrap` target by its name, and is
-    now refused once it declares `"floating_point"`. ([#4628](https://github.com/zarr-developers/zarr-python/pull/4628))
+- **Breaking:** `create_default` derives each member that depends on a member given, unless that member is given too. A data type brings its default fill value and, in v3, its array -> bytes codec: `vlen-utf8` for `string`, `vlen-bytes` for `bytes` and `variable_length_bytes`, and `bytes` otherwise, so `ZarrV3ArrayMetadata.create_default(data_type="string")` now works. Some defaults change: a time data type gets `"NaT"` where it got `0`, `|O` gets `null` where it got `0`, and in v2 `|b1` gets `false`, `|S` and `<U` get `""`, and `|V` and structs get null bytes, where these got `null`. The defaults come from new hooks on a data type definition, `fill_value_default` and, in v3, `array_bytes_codec_default`, so an extension data type can declare its own, with `ConstantFillValue` for a default that does not depend on the configuration. `zarr_metadata.definition.default_fill_value` and `zarr_metadata.v3.definition.default_array_bytes_codec` read them. ([#4621](https://github.com/zarr-developers/zarr-python/pull/4621))
+
+- **Breaking:** A v3 codec is defined with the class of its kind, `ArrayArrayCodecDefinition`, `ArrayBytesCodecDefinition` or `BytesBytesCodecDefinition`, instead of `CodecDefinition(kind=...)`, and `CodecDefinition` is now their abstract base. Only a codec that receives an array, an `ArrayCodecDefinition`, takes `chunk_rules` and `pipelines`, and only an array -> array codec takes `transition`, so giving one to a codec that cannot use it is a `TypeError`.
+
+    A v3 data type definition declares what kind of numbers its values are with `number_class`, a `NumberClass`: `"integral"`, `"floating_point"`, `"complex"` or `"non_numeric"`. `cast_value` and `scale_offset` read it instead of a list of data type names, so a data type defined elsewhere is judged by what it declares: both refuse one that declares complex or non-numeric values, `cast_value` refuses to `wrap` to one that declares floating-point values, and one that declares no number class is accepted by both, as before. ([#4628](https://github.com/zarr-developers/zarr-python/pull/4628))
 
 ### Bugfixes
 
 - `ZarrV2ArrayMetadata.create_default(shape=...)` derives a chunk length of 1 for a dimension of length 0, as the v3 model does, where it wrote 0, which zarr-python repairs to 1 on read. ([#4621](https://github.com/zarr-developers/zarr-python/pull/4621))
 
-- **Breaking:** `cast_value` and `scale_offset` refuse the data types their
-    specs do not list. Each spec names the integer and floating-point types as
-    "the following data types defined in this repository" that it supports, and
-    that repository also defines the numpy time types and the complex types. So
-    both codecs now refuse `numpy.datetime64` and `numpy.timedelta64`, and
-    `cast_value` refuses them as the data type it casts to, and `scale_offset`
-    now refuses `complex64` and `complex128`. All of these were accepted. The time
-    types' own spec says they are "compatible with any codec that supports arrays
-    of signed 64-bit integers", which the two codecs' specs do not bear out.
-    `zarr_metadata.testing.strategies` no longer draws these combinations. ([#4628](https://github.com/zarr-developers/zarr-python/pull/4628))
+- **Breaking:** `cast_value` and `scale_offset` refuse data types their specs do not list, which they accepted: both refuse `numpy.datetime64` and `numpy.timedelta64`, which `cast_value` also refuses as the data type it casts to, and `scale_offset` refuses `complex64` and `complex128`. `zarr_metadata.testing.strategies` no longer draws these combinations. ([#4628](https://github.com/zarr-developers/zarr-python/pull/4628))
 
 ### Deprecations and Removals