From 185be37806c712209f18410677954b8afec2c43e Mon Sep 17 00:00:00 2001
From: Davis Vann Bennett <davis.v.bennett@gmail.com>
Date: Wed, 11 Nov 2026 21:36:50 +0100
Subject: [PATCH] docs(zarr-metadata): condense the pending release notes and
 renumber the #4598 fragment

Replace the ten bugfix fragments of #4574 with three, two of them marked
breaking, and shorten the #4592 fragment to the rename and the names a
user is most likely to have imported. The removed detail stays in the
pull requests.

Rename 427.removal.md to 4598.removal.md: the fragment came in with
#4598 but carried the fork PR's number, so the changelog would have
linked to an unrelated upstream PR.

Assisted-by: ClaudeCode:claude-opus-5-5
---
 packages/zarr-metadata/changes/4574.bugfix.1.md      |  8 +-------
 packages/zarr-metadata/changes/4574.bugfix.10.md     |  5 -----
 packages/zarr-metadata/changes/4574.bugfix.2.md      |  5 +----
 packages/zarr-metadata/changes/4574.bugfix.3.md      |  6 +-----
 packages/zarr-metadata/changes/4574.bugfix.4.md      |  7 -------
 packages/zarr-metadata/changes/4574.bugfix.5.md      | 11 -----------
 packages/zarr-metadata/changes/4574.bugfix.6.md      |  8 --------
 packages/zarr-metadata/changes/4574.bugfix.7.md      | 12 ------------
 packages/zarr-metadata/changes/4574.bugfix.8.md      |  4 ----
 packages/zarr-metadata/changes/4574.bugfix.9.md      | 12 ------------
 packages/zarr-metadata/changes/4592.removal.md       | 11 +----------
 .../changes/{427.removal.md => 4598.removal.md}      |  0
 12 files changed, 4 insertions(+), 85 deletions(-)
 delete mode 100644 packages/zarr-metadata/changes/4574.bugfix.10.md
 delete mode 100644 packages/zarr-metadata/changes/4574.bugfix.4.md
 delete mode 100644 packages/zarr-metadata/changes/4574.bugfix.5.md
 delete mode 100644 packages/zarr-metadata/changes/4574.bugfix.6.md
 delete mode 100644 packages/zarr-metadata/changes/4574.bugfix.7.md
 delete mode 100644 packages/zarr-metadata/changes/4574.bugfix.8.md
 delete mode 100644 packages/zarr-metadata/changes/4574.bugfix.9.md
 rename packages/zarr-metadata/changes/{427.removal.md => 4598.removal.md} (100%)

diff --git a/packages/zarr-metadata/changes/4574.bugfix.1.md b/packages/zarr-metadata/changes/4574.bugfix.1.md
index 0d387acd14..53a5935723 100644
--- a/packages/zarr-metadata/changes/4574.bugfix.1.md
+++ b/packages/zarr-metadata/changes/4574.bugfix.1.md
@@ -1,7 +1 @@
-**Breaking:** A problem in a v2 struct dtype is located where the document
-    writes it. A record's problem was located under a `fields` key the
-    document does not have, at `("dtype", "fields", 0, 1)`; it is now at
-    `("dtype", 0, 1)`, and carries the value found there as its `input`.
-    `declarations()` places each record's type there too. A definition's
-    functions still find the record types in `nested` at
-    `("fields", 0, 1)`, their place in the configuration.
+**Breaking:** Every problem is now located where the document writes the value. The v2 readers and the v2 models' `from_key_value` locate a problem in the file that holds it, such as `(".zarray", "order")` or `(".zattrs", "x")`, instead of in the merged document, and a v2 array node reading's `at` is now `(".zarray",)`. A problem in a v2 struct record is at `("dtype", 0, 1)` instead of under a `fields` key the document does not have, a codec's missing configuration member, such as the `endian` of a `bytes` codec, is reported inside the configuration it writes, or at `codecs.N.configuration` when it writes none, and a codec handed values it cannot encode is reported at `codecs.N` however it is spelled.
diff --git a/packages/zarr-metadata/changes/4574.bugfix.10.md b/packages/zarr-metadata/changes/4574.bugfix.10.md
deleted file mode 100644
index e06b2d6d3d..0000000000
--- a/packages/zarr-metadata/changes/4574.bugfix.10.md
+++ /dev/null
@@ -1,5 +0,0 @@
-Each problem `read_consolidated_metadata_v3` finds in the inline
-    `consolidated_metadata` member itself, such as a `kind` that is not
-    `"inline"` or a key that is not a node path, carries the value found at
-    its location as its `input`, as every other reader's problems do. Its
-    `input` was unset.
diff --git a/packages/zarr-metadata/changes/4574.bugfix.2.md b/packages/zarr-metadata/changes/4574.bugfix.2.md
index 4342fc151c..b0a67f448e 100644
--- a/packages/zarr-metadata/changes/4574.bugfix.2.md
+++ b/packages/zarr-metadata/changes/4574.bugfix.2.md
@@ -1,4 +1 @@
-A v2 dtype written as the string `"struct"` is refused as a string that is
-    not a NumPy typestr, like any other, instead of being read as a struct
-    with no records. `struct` is the name the definition of a records array
-    is filed under, not part of the v2 dtype grammar.
+**Breaking:** The v2 readers now agree with the v3 readers. A `.zarray` member the spec does not define may hold `NaN` and the infinities, a `.zmetadata` key that does not name its node's path, such as `/a/.zarray`, is refused instead of being read as the node at `a`, and a `.zgroup` that holds `attributes` is an `invalid_value` rather than an `unknown_key`, so a caller who tolerates unknown keys no longer drops those attributes.
diff --git a/packages/zarr-metadata/changes/4574.bugfix.3.md b/packages/zarr-metadata/changes/4574.bugfix.3.md
index adec05b00c..b69507e86d 100644
--- a/packages/zarr-metadata/changes/4574.bugfix.3.md
+++ b/packages/zarr-metadata/changes/4574.bugfix.3.md
@@ -1,5 +1 @@
-A group listed in v3 consolidated metadata whose own document has a problem,
-    such as attributes that are not an object, is reported for that problem
-    alone. It was also reported for disagreeing with the outer listing's copy
-    of the same node, a difference that came only from the problem. A copy
-    whose only problem is an unknown key is still compared.
+Various mistakes in v2 and consolidated metadata are now reported once, at their own location, with the right kind and message. A float where an integer from a fixed set is required, such as `"zarr_format": 2.0`, is an `invalid_type`, and a v2 typestr with a part its family does not take, such as `<f4[ns]`, or a time typestr without a unit, is a single `invalid_value` that names the part. A struct record of the wrong length or with a non-string name, the string `"struct"` given as a v2 dtype, a node that v3 consolidated metadata lists and whose own document has a problem, and a malformed inline `consolidated_metadata` member are each reported for their own problem alone, with the value found there as the problem's `input`.
diff --git a/packages/zarr-metadata/changes/4574.bugfix.4.md b/packages/zarr-metadata/changes/4574.bugfix.4.md
deleted file mode 100644
index c9dffad04b..0000000000
--- a/packages/zarr-metadata/changes/4574.bugfix.4.md
+++ /dev/null
@@ -1,7 +0,0 @@
-A v2 struct record of the wrong length is reported as "expected an array of
-    2 or 3 elements", where the message named only the three-element form. A
-    two-element record whose name is not a string, `[5, "<f4"]`, is reported
-    at the name, where it was reported as a record of the wrong length. The
-    checker behind `zarr_metadata.typed_json.check` tries an array only
-    against the union branches of its length, and names a union of arrays of
-    fixed lengths by those lengths.
diff --git a/packages/zarr-metadata/changes/4574.bugfix.5.md b/packages/zarr-metadata/changes/4574.bugfix.5.md
deleted file mode 100644
index fc9592094b..0000000000
--- a/packages/zarr-metadata/changes/4574.bugfix.5.md
+++ /dev/null
@@ -1,11 +0,0 @@
-**Breaking:** The v2 readers agree with the v3 readers in three places. A
-    `.zarray` member the spec does not define may hold `NaN` and the
-    infinities, as a v3 member that nothing claims may, in a store and in a
-    `.zmetadata` alike. A `.zmetadata` key that does not name its node's
-    path, such as `/a/.zarray` or `a//b/.zarray`, is refused, as a v3
-    listing refuses such a key, instead of being read as the node at `a` or
-    `a/b`; zarr-python looks an entry up by its node's path and never finds
-    one written otherwise. A `.zgroup` that holds `attributes` is an
-    `invalid_value`, as a `.zarray` that holds them is, not an
-    `unknown_key`, so a caller who tolerates unknown keys does not drop the
-    attributes it holds.
diff --git a/packages/zarr-metadata/changes/4574.bugfix.6.md b/packages/zarr-metadata/changes/4574.bugfix.6.md
deleted file mode 100644
index 73ad98f4d2..0000000000
--- a/packages/zarr-metadata/changes/4574.bugfix.6.md
+++ /dev/null
@@ -1,8 +0,0 @@
-A v2 typestr with a part its family does not take, such as `<f4[ns]` or
-    `|O4`, is refused with one `invalid_value` problem that names the part:
-    "expected a typestr of the float family without a unit, got "<f4[ns]"".
-    It was refused as one `unknown_key` problem per internal configuration
-    key (`unit`, `scale_factor`, `itemsize`), a kind a caller who tolerates
-    unknown keys leaves out, so such a caller read the typestr as valid. A
-    time typestr without a unit, `<M8`, is an `invalid_value` too, not a
-    `missing_key`.
diff --git a/packages/zarr-metadata/changes/4574.bugfix.7.md b/packages/zarr-metadata/changes/4574.bugfix.7.md
deleted file mode 100644
index 4d1227150c..0000000000
--- a/packages/zarr-metadata/changes/4574.bugfix.7.md
+++ /dev/null
@@ -1,12 +0,0 @@
-A definition's rules are located where the document writes the declaration. A
-    `bytes` codec written as `"bytes"` or `{"name": "bytes"}`, with values
-    of several bytes, reports its missing `endian` at
-    `codecs.N.configuration`, the configuration it does not write, as a
-    codec that requires a configuration does; it was reported at
-    `codecs.N.configuration.endian`, inside a configuration that is not
-    there. A codec handed values it cannot encode, such as a `bytes` codec
-    handed a data type of varying size, is reported at `codecs.N` however it
-    is spelled, where it was reported at `codecs.N.configuration`: a chunk
-    rule's problem at the configuration as a whole is the codec's. A
-    definition's `rules` still report such a problem at the configuration
-    the document writes.
diff --git a/packages/zarr-metadata/changes/4574.bugfix.8.md b/packages/zarr-metadata/changes/4574.bugfix.8.md
deleted file mode 100644
index d7149876ab..0000000000
--- a/packages/zarr-metadata/changes/4574.bugfix.8.md
+++ /dev/null
@@ -1,4 +0,0 @@
-A float given where a document requires one of a set of integers, such as
-    `"zarr_format": 2.0`, is an `invalid_type`, as `4.0` in `shape` is and
-    as a blosc `"shuffle": 1.0` already was. It was an `invalid_value`
-    wherever the set stood alone, so one mistake had two kinds.
diff --git a/packages/zarr-metadata/changes/4574.bugfix.9.md b/packages/zarr-metadata/changes/4574.bugfix.9.md
deleted file mode 100644
index e51f5dc30f..0000000000
--- a/packages/zarr-metadata/changes/4574.bugfix.9.md
+++ /dev/null
@@ -1,12 +0,0 @@
-**Breaking:** `read_node_metadata_v2`, `read_repaired_node_metadata_v2`
-    and the v2 models' `from_key_value` locate each problem in the file that
-    holds it, `(".zarray", "order")` or `(".zattrs", "x")`, as
-    `read_consolidated_metadata_v2` locates it in its entry. They located
-    problems in the merged document, so a `.zarray` that wrote `attributes`
-    beside a `.zattrs` that was not an object gave two problems at
-    `("attributes",)`, a location in neither file. An array node's reading
-    locates its declarations there too: its new `at` is `(".zarray",)`, so
-    `declarations()` gives `(".zarray", "dtype")` and `with_problems` pairs each
-    declaration with its problems. Its model reads the merged document, so the
-    model's own `reading` locates the declaration at `("dtype",)`, and no longer
-    equals the node reading.
diff --git a/packages/zarr-metadata/changes/4592.removal.md b/packages/zarr-metadata/changes/4592.removal.md
index 5080a931ea..323ce4de30 100644
--- a/packages/zarr-metadata/changes/4592.removal.md
+++ b/packages/zarr-metadata/changes/4592.removal.md
@@ -1,10 +1 @@
-Rename the word for a value at an extension point: it is now a *declaration* (it was a *field*). A name/value pair in a JSON metadata object stays a *member*. The package already said *field* in the JSON sense in `extra_fields`, `ExtraFieldDefinition`, `ZarrV3ExtensionField` and `must_understand_fields`, after the spec's "additional fields", so one word meant two things. The public names change with no aliases:
-
-- `AcceptedField`, `UnclaimedField`, `RefusedField` and `ResolvedField` are now `AcceptedDeclaration`, `UnclaimedDeclaration`, `RefusedDeclaration` and `ResolvedDeclaration`.
-- `ZarrV3DataTypeField`, `ZarrV3ChunkGridField`, `ZarrV3ChunkKeyEncodingField`, `ZarrV3CodecField`, `ZarrV3StaticCodecField`, `ZarrV3StorageTransformerField` and `ZarrV2DataTypeField` are now the same names ending in `Declaration`, and a kind's `field_aliases` is now `declaration_aliases`.
-- `ZarrV3MetadataFieldJSON` is now `ZarrV3DeclarationJSON`, and `field_json_schema_v3` is now `declaration_json_schema_v3`.
-- A reading's `fields()` is now `declarations()`, and a model's `unclaimed_fields` is now `unclaimed_declarations`.
-- The first parameter of `with_problems` is now `declarations` (it was `fields`).
-- The JSON Schemas that `node_metadata_json_schema_v3` and `declaration_json_schema_v3` write name each alias under `$defs` by its new name, so a `$ref` to `#/$defs/ZarrV3CodecField` is now `#/$defs/ZarrV3CodecDeclaration`, and likewise for the other kinds.
-
-Messages that said *field* or *metadata field* for an extension-point value now say *declaration*, as in "expected a declaration (string or extension object)". Prose that said *extra member* or *extension member* now says *extra field* and *extension field*, after the names. `extra_fields`, `ExtraFieldDefinition`, `ZarrV3ExtensionField`, `StructField` and the pydantic `...MetadataField` types keep their names.
+**Breaking:** The value found at an extension point, a data type, chunk grid, chunk key encoding, codec or storage transformer, is now called a *declaration*. The word *field* also meant a key of a metadata object, as in `extra_fields`, so one word meant two things. The public names change with no aliases: `AcceptedField`, `UnclaimedField`, `RefusedField` and `ResolvedField` end in `Declaration`, as do `ZarrV3CodecField` and the other kind-specific `...Field` types; a reading's `fields()` is `declarations()`; a model's `unclaimed_fields` is `unclaimed_declarations`; `ZarrV3MetadataFieldJSON` is `ZarrV3DeclarationJSON`; `field_json_schema_v3` is `declaration_json_schema_v3`; a kind's `field_aliases` is `declaration_aliases`; the first parameter of `with_problems` is `declarations`; and the JSON Schema `$defs` use the new names. `extra_fields`, `ExtraFieldDefinition`, `ZarrV3ExtensionField` and `StructField` keep their names.
diff --git a/packages/zarr-metadata/changes/427.removal.md b/packages/zarr-metadata/changes/4598.removal.md
similarity index 100%
rename from packages/zarr-metadata/changes/427.removal.md
rename to packages/zarr-metadata/changes/4598.removal.md