rabernat · rabernat · Nov 8, 2025 · Nov 11, 2025 · Nov 13, 2025 · Nov 13, 2025
diff --git a/.github/workflows/check_changelogs.yml b/.github/workflows/check_changelogs.yml
@@ -9,10 +9,10 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      - uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 # v6.0.0
 
       - name: Install uv
-        uses: astral-sh/setup-uv@85856786d1ce8acfbcc2f13a5f3fbd6b938f9f41 # v7.1.2
+        uses: astral-sh/setup-uv@1e862dfacbd1d6d858c55d9b792c756523627244 # v7.1.4
 
       - name: Check changelog entries
         run: uv run --no-sync python ci/check_changelog_entries.py
diff --git a/.github/workflows/gpu_test.yml b/.github/workflows/gpu_test.yml
@@ -29,7 +29,7 @@ jobs:
         dependency-set: ["minimal"]
 
     steps:
-    - uses: actions/checkout@v5
+    - uses: actions/checkout@v6
       with:
         fetch-depth: 0  # grab all branches and tags
     # - name: cuda-toolkit

diff --git a/.github/workflows/hypothesis.yaml b/.github/workflows/hypothesis.yaml
@@ -28,7 +28,7 @@ jobs:
         dependency-set: ["optional"]
 
     steps:
-    - uses: actions/checkout@v5
+    - uses: actions/checkout@v6
     - name: Set HYPOTHESIS_PROFILE based on trigger
       run: |
         if [[ "${{ github.event_name }}" == "schedule" || "${{ github.event_name }}" == "workflow_dispatch" ]]; then

diff --git a/.github/workflows/nightly_wheels.yml b/.github/workflows/nightly_wheels.yml
@@ -12,7 +12,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
         with:
           submodules: true
           fetch-depth: 0

diff --git a/.github/workflows/releases.yml b/.github/workflows/releases.yml
@@ -11,7 +11,7 @@ jobs:
       fail-fast: false
 
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
         with:
           submodules: true
           fetch-depth: 0

diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
@@ -44,7 +44,7 @@ jobs:
     runs-on: ${{ matrix.os }}
 
     steps:
-    - uses: actions/checkout@v5
+    - uses: actions/checkout@v6
       with:
         fetch-depth: 0  # grab all branches and tags
     - name: Set up Python
@@ -86,7 +86,7 @@ jobs:
           - python-version: "3.11"
             dependency-set: upstream
     steps:
-    - uses: actions/checkout@v5
+    - uses: actions/checkout@v6
       with:
         fetch-depth: 0
     - name: Set up Python
@@ -115,7 +115,7 @@ jobs:
     name: doctests
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v5
+    - uses: actions/checkout@v6
       with:
         fetch-depth: 0 # required for hatch version discovery, which is needed for numcodecs.zarr3
     - name: Set up Python

diff --git a/changes/3118.doc.md b/changes/3118.doc.md
diff --git a/changes/3303.doc.md b/changes/3303.doc.md
diff --git a/changes/3366.feature.md b/changes/3366.feature.md
diff --git a/changes/3483.bugfix.md b/changes/3483.bugfix.md
diff --git a/changes/3490.feature.md b/changes/3490.feature.md
diff --git a/changes/3502.doc.md b/changes/3502.doc.md
diff --git a/changes/3515.misc.md b/changes/3515.misc.md
diff --git a/changes/3526.feature.md b/changes/3526.feature.md
diff --git a/changes/3530.bugfix.md b/changes/3530.bugfix.md
diff --git a/changes/3532.misc.md b/changes/3532.misc.md
diff --git a/changes/3533.misc.md b/changes/3533.misc.md
diff --git a/changes/3535.bugfix.md b/changes/3535.bugfix.md
diff --git a/changes/3536.doc.md b/changes/3536.doc.md
diff --git a/changes/3553.misc.md b/changes/3553.misc.md
diff --git a/changes/3560.bugfix.md b/changes/3560.bugfix.md
diff --git a/changes/3603.bugfix.md b/changes/3603.bugfix.md
@@ -0,0 +1 @@
+Correct the target bytes number for auto-chunking when auto-sharding.
diff --git a/changes/3605.misc.md b/changes/3605.misc.md
@@ -0,0 +1 @@
+Fix a bug in the test suite that prevented stand-alone example scripts from being tested.
diff --git a/docs/api/buffer.md b/docs/api/buffer.md
diff --git a/docs/api/testing.md b/docs/api/testing.md
diff --git a/docs/api/abc/buffer.md → docs/api/zarr/abc/buffer.md b/docs/api/abc/buffer.md → docs/api/zarr/abc/buffer.md
diff --git a/docs/api/abc/codec.md → docs/api/zarr/abc/codec.md b/docs/api/abc/codec.md → docs/api/zarr/abc/codec.md
@@ -3,4 +3,3 @@ title: codec
 ---
 
 ::: zarr.abc.codec
-::: zarr.abc.numcodec
diff --git a/docs/api/zarr/abc/index.md b/docs/api/zarr/abc/index.md
@@ -0,0 +1,7 @@
+## Abstract base classes
+
+- **[buffer](./buffer.md)** - Providing access to underlying memory via [buffers](https://docs.python.org/3/c-api/buffer.html)
+- **[codec](./codec.md)** - Expressing [zarr codecs](https://zarr-specs.readthedocs.io/en/latest/v3/core/index.html#chunk-encoding)
+- **[metadata](./metadata.md)** - Creating metadata classes compatible with the Zarr API
+- **[numcodec](./numcodec.md)** - Protocols and classes for modeling codec interface used by numcodecs
+- **[store](./store.md)** - ABC for implementing Zarr stores and managing getting and setting bytes in a store
diff --git a/docs/api/abc/metadata.md → docs/api/zarr/abc/metadata.md b/docs/api/abc/metadata.md → docs/api/zarr/abc/metadata.md
diff --git a/docs/api/zarr/abc/numcodec.md b/docs/api/zarr/abc/numcodec.md
@@ -0,0 +1,5 @@
+---
+title: numcodec
+---
+
+::: zarr.abc.numcodec
diff --git a/docs/api/abc/store.md → docs/api/zarr/abc/store.md b/docs/api/abc/store.md → docs/api/zarr/abc/store.md
diff --git a/docs/api/api_async.md → docs/api/zarr/api/asynchronous.md b/docs/api/api_async.md → docs/api/zarr/api/asynchronous.md
diff --git a/docs/api/zarr/api/index.md b/docs/api/zarr/api/index.md
@@ -0,0 +1,5 @@
+---
+title: API
+---
+
+Zarr provides both an [async](./asynchronous.md) and a [sync](./synchronous.md) API. See those pages for more details.
diff --git a/docs/api/api_sync.md → docs/api/zarr/api/synchronous.md b/docs/api/api_sync.md → docs/api/zarr/api/synchronous.md
diff --git a/docs/api/array.md → docs/api/zarr/array.md b/docs/api/array.md → docs/api/zarr/array.md
diff --git a/docs/api/zarr/buffer/cpu.md b/docs/api/zarr/buffer/cpu.md
@@ -0,0 +1 @@
+::: zarr.buffer.cpu
diff --git a/docs/api/zarr/buffer/gpu.md b/docs/api/zarr/buffer/gpu.md
@@ -0,0 +1 @@
+::: zarr.buffer.gpu
diff --git a/docs/api/zarr/buffer/index.md b/docs/api/zarr/buffer/index.md
@@ -0,0 +1,3 @@
+Zarr provides buffer classes for both the [cpu](./cpu.md) and [gpu](./gpu.md). Generic buffer functionality is also detailed below.
+
+::: zarr.buffer
diff --git a/docs/api/codecs.md → docs/api/zarr/codecs.md b/docs/api/codecs.md → docs/api/zarr/codecs.md
@@ -3,5 +3,3 @@ title: codecs
 ---
 
 ::: zarr.codecs
-
-::: zarr.codecs.numcodecs
diff --git a/docs/api/zarr/codecs/numcodecs.md b/docs/api/zarr/codecs/numcodecs.md
@@ -0,0 +1,5 @@
+---
+title: numcodecs
+---
+
+::: zarr.codecs.numcodecs
diff --git a/docs/api/config.md → docs/api/zarr/config.md b/docs/api/config.md → docs/api/zarr/config.md
diff --git a/docs/api/convenience.md → docs/api/zarr/convenience.md b/docs/api/convenience.md → docs/api/zarr/convenience.md
diff --git a/docs/api/create.md → docs/api/zarr/create.md b/docs/api/create.md → docs/api/zarr/create.md
diff --git a/docs/api/deprecated/convenience.md → docs/api/zarr/deprecated/convenience.md b/docs/api/deprecated/convenience.md → docs/api/zarr/deprecated/convenience.md
diff --git a/docs/api/deprecated/creation.md → docs/api/zarr/deprecated/creation.md b/docs/api/deprecated/creation.md → docs/api/zarr/deprecated/creation.md
diff --git a/docs/api/dtype.md → docs/api/zarr/dtype.md b/docs/api/dtype.md → docs/api/zarr/dtype.md
diff --git a/docs/api/errors.md → docs/api/zarr/errors.md b/docs/api/errors.md → docs/api/zarr/errors.md
diff --git a/docs/api/group.md → docs/api/zarr/group.md b/docs/api/group.md → docs/api/zarr/group.md
diff --git a/docs/api/index.md → docs/api/zarr/index.md b/docs/api/index.md → docs/api/zarr/index.md
@@ -38,8 +38,8 @@ Complete reference documentation for the Zarr-Python API.
 
 Zarr-Python provides both synchronous and asynchronous APIs:
 
-- **[Async API](api_async.md)** - Asynchronous operations for concurrent access
-- **[Sync API](api_sync.md)** - Synchronous operations for simple usage
+- **[Async API](./api/asynchronous.md)** - Asynchronous operations for concurrent access
+- **[Sync API](./api/synchronous.md)** - Synchronous operations for simple usage
 
 ## Abstract Base Classes
 
@@ -52,7 +52,7 @@ The ABC module defines interfaces for extending Zarr:
 ## Utilities
 
 - **[Errors](errors.md)** - Exception classes and error handling
-- **[Testing](testing.md)** - Utilities for testing Zarr-based code
+- **[Testing](testing/index.md)** - Utilities for testing Zarr-based code
 
 
 ## Migration and Compatibility
@@ -64,7 +64,7 @@ These deprecated modules are maintained for backward compatibility but should be
 
 ## Getting Help
 
-- Check the [User Guide](../user-guide/index.md) for tutorials and examples
+- Check the [User Guide](../../user-guide/index.md) for tutorials and examples
 - Browse function signatures and docstrings in the API reference
 - Report issues on [GitHub](https://github.com/zarr-developers/zarr-python)
 - Join discussions on the [Zarr community forum](https://github.com/zarr-developers/community)
diff --git a/docs/api/load.md → docs/api/zarr/load.md b/docs/api/load.md → docs/api/zarr/load.md
diff --git a/docs/api/metadata.md → docs/api/zarr/metadata.md b/docs/api/metadata.md → docs/api/zarr/metadata.md
diff --git a/docs/api/open.md → docs/api/zarr/open.md b/docs/api/open.md → docs/api/zarr/open.md
diff --git a/docs/api/registry.md → docs/api/zarr/registry.md b/docs/api/registry.md → docs/api/zarr/registry.md
diff --git a/docs/api/save.md → docs/api/zarr/save.md b/docs/api/save.md → docs/api/zarr/save.md
diff --git a/docs/api/storage.md → docs/api/zarr/storage.md b/docs/api/storage.md → docs/api/zarr/storage.md
diff --git a/docs/api/zarr/testing/buffer.md b/docs/api/zarr/testing/buffer.md
@@ -0,0 +1,3 @@
+## Buffer
+
+::: zarr.testing.buffer
diff --git a/docs/api/zarr/testing/conftest.md b/docs/api/zarr/testing/conftest.md
@@ -0,0 +1,3 @@
+## Conftest
+
+::: zarr.testing.conftest
diff --git a/docs/api/zarr/testing/index.md b/docs/api/zarr/testing/index.md
@@ -0,0 +1,12 @@
+---
+title: testing
+---
+
+See the following sub-modules:
+
+- [buffer](./buffer.md)
+- [conftest](./conftest.md)
+- [stateful](./stateful.md)
+- [store](./store.md)
+- [strategies](./strategies.md)
+- [utils](./utils.md)
diff --git a/docs/api/zarr/testing/stateful.md b/docs/api/zarr/testing/stateful.md
@@ -0,0 +1,3 @@
+## Stateful
+
+::: zarr.testing.stateful
diff --git a/docs/api/zarr/testing/store.md b/docs/api/zarr/testing/store.md
@@ -0,0 +1,4 @@
+
+## Store
+
+::: zarr.testing.store
diff --git a/docs/api/zarr/testing/strategies.md b/docs/api/zarr/testing/strategies.md
@@ -0,0 +1,4 @@
+
+## Strategies
+
+::: zarr.testing.strategies
diff --git a/docs/api/zarr/testing/utils.md b/docs/api/zarr/testing/utils.md
@@ -0,0 +1,3 @@
+## Utils
+
+::: zarr.testing.utils
diff --git a/docs/index.md b/docs/index.md
@@ -52,7 +52,7 @@ conda install --channel conda-forge zarr
     A detailed guide for how to use Zarr-Python.
 
 
--   [:material-api:{ .lg .middle } __API Reference__](api/open.md)
+-   [:material-api:{ .lg .middle } __API Reference__](api/zarr/open.md)
 
     ---
 

diff --git a/docs/release-notes.md b/docs/release-notes.md
@@ -2,16 +2,55 @@
 
 <!-- towncrier release notes start -->
 
-# zarr 3.1.3 (2025-09-18)
+# zarr 3.1.5 (2025-11-21)
 
-## Features
+## Bugfixes
+
+- Fix formatting errors in the release notes section of the docs. ([#3594](https://github.com/zarr-developers/zarr-python/issues/3594))
+
+
+## 3.1.4 (2025-11-20)
+
+### Features
+
+- The `Array` class can now also be parametrized in the same manner as the `AsyncArray` class, allowing Zarr format v2 and v3 `Array`s to be distinguished.
+  New types have been added to `zarr.types` to help with this. ([#3304](https://github.com/zarr-developers/zarr-python/issues/3304))
+- Adds `zarr.experimental.cache_store.CacheStore`, a `Store` that implements caching by combining two other `Store` instances. See the [docs page](https://zarr.readthedocs.io/en/latest/user-guide/experimental#cachestore) for more information about this feature. ([#3366](https://github.com/zarr-developers/zarr-python/issues/3366))
+- Adds a `zarr.experimental` module for unstable user-facing features. ([#3490](https://github.com/zarr-developers/zarr-python/issues/3490))
+- Add a `array.target_shard_size_bytes` to [`zarr.config`][] to allow users to set a maximum number of bytes per-shard when `shards="auto"` in, for example, [`zarr.create_array`][]. ([#3547](https://github.com/zarr-developers/zarr-python/issues/3547))
+- Make `async_array` on the [`zarr.Array`][] class public (`_async_array` will remain untouched, but its stability is not guaranteed). ([#3556](https://github.com/zarr-developers/zarr-python/issues/3556))
+
+### Bugfixes
+
+- Fix a bug that prevented `PCodec` from being properly resolved when loading arrays using that compressor. ([#3483](https://github.com/zarr-developers/zarr-python/issues/3483))
+- Fixed a bug that prevented Zarr Python from opening Zarr V3 array metadata documents that contained
+   extra keys with permissible values (dicts with a `"must_understand"` key set to `"false"`). ([#3530](https://github.com/zarr-developers/zarr-python/issues/3530))
+- Fixed a bug where the `"consolidated_metadata"` key was written to metadata documents even when
+  consolidated metadata was not used, resulting in invalid metadata documents. ([#3535](https://github.com/zarr-developers/zarr-python/issues/3535))
+- Improve write performance to large shards by up to 10x. ([#3560](https://github.com/zarr-developers/zarr-python/issues/3560))
+
+### Improved Documentation
+
+- Use mkdocs-material for Zarr-Python documentation ([#3118](https://github.com/zarr-developers/zarr-python/issues/3118))
+- Document different values of StoreLike with examples in the user guide. ([#3303](https://github.com/zarr-developers/zarr-python/issues/3303))
+- Reorganize the top-level `examples` directory to give each example its own sub-directory. Adds content to the docs for each example. ([#3502](https://github.com/zarr-developers/zarr-python/issues/3502))
+- Updated 3.0 Migration Guide to include function signature change to zarr.Array.resize function. ([#3536](https://github.com/zarr-developers/zarr-python/issues/3536))
+
+### Misc
+
+- [#3515](https://github.com/zarr-developers/zarr-python/issues/3515), [#3532](https://github.com/zarr-developers/zarr-python/issues/3532), [#3533](https://github.com/zarr-developers/zarr-python/issues/3533), [#3553](https://github.com/zarr-developers/zarr-python/issues/3553)
+
+
+## zarr 3.1.3 (2025-09-18)
+
+### Features
 
 - Add a command-line interface to migrate v2 Zarr metadata to v3. Corresponding functions are also provided under zarr.metadata. ([#1798](https://github.com/zarr-developers/zarr-python/issues/1798))
 - Add obstore implementation of delete_dir. ([#3310](https://github.com/zarr-developers/zarr-python/issues/3310))
 - Adds a registry for chunk key encodings for extensibility. This allows users to implement a custom `ChunkKeyEncoding`, which can be registered via `register_chunk_key_encoding` or as an entry point under `zarr.chunk_key_encoding`. ([#3436](https://github.com/zarr-developers/zarr-python/issues/3436))
 - Trying to open a group at a path where an array already exists now raises a helpful error. ([#3444](https://github.com/zarr-developers/zarr-python/issues/3444))
 
-## Bugfixes
+### Bugfixes
 
 - Prevents creation of groups (.create_group) or arrays (.create_array) as children of an existing array. ([#2582](https://github.com/zarr-developers/zarr-python/issues/2582))
 - Fix a bug preventing `ones_like`, `full_like`, `empty_like`, `zeros_like` and `open_like` functions from accepting an explicit specification of array attributes like shape, dtype, chunks etc. The functions `full_like`, `empty_like`, and `open_like` now also more consistently infer a `fill_value` parameter from the provided array. ([#2992](https://github.com/zarr-developers/zarr-python/issues/2992))
@@ -22,11 +61,11 @@
 - Creating a new group with `zarr.group` no longer errors. This fixes a regression introduced in version 3.1.2. ([#3431](https://github.com/zarr-developers/zarr-python/issues/3431))
 - Setting `fill_value` to a float like `0.0` when the data type of the array is an integer is a common mistake. This change lets Zarr Python read arrays with this erroneous metadata, although Zarr Python will not create such arrays. ([#3448](https://github.com/zarr-developers/zarr-python/issues/3448))
 
-## Deprecations and Removals
+### Deprecations and Removals
 
 - The `Store.set_partial_writes` method, which was not used by Zarr-Python, has been removed. `store.supports_partial_writes` is now always `False`. ([#2859](https://github.com/zarr-developers/zarr-python/issues/2859))
 
-## Misc
+### Misc
 
 - [#3376](https://github.com/zarr-developers/zarr-python/issues/3376), [#3390](https://github.com/zarr-developers/zarr-python/issues/3390), [#3403](https://github.com/zarr-developers/zarr-python/issues/3403), [#3449](https://github.com/zarr-developers/zarr-python/issues/3449)
 

diff --git a/docs/user-guide/arrays.md b/docs/user-guide/arrays.md
@@ -27,7 +27,7 @@ columns (and so there will be 100 chunks in total). The data is written to a
 and see [Data types](data_types.md) for an in-depth look at the data types supported
 by Zarr.
 
-See the [creation API documentation](../api/create.md) for more detailed information about
+See the [creation API documentation](../api/zarr/create.md) for more detailed information about
 creating arrays.
 
 ## Reading and writing data
@@ -213,7 +213,7 @@ built-in delta filter:
 
 ```python exec="true" session="arrays" source="above" result="ansi"
 import lzma
-from numcodecs.zarr3 import LZMA
+from zarr.codecs.numcodecs import LZMA
 
 lzma_filters = [dict(id=lzma.FILTER_DELTA, dist=4), dict(id=lzma.FILTER_LZMA2, preset=1)]
 compressors = LZMA(filters=lzma_filters)
@@ -251,7 +251,7 @@ mechanism for configuring filters outside of the primary compressor.
 Here is an example using a delta filter with the Blosc compressor:
 
 ```python exec="true" session="arrays" source="above" result="ansi"
-from numcodecs.zarr3 import Delta
+from zarr.codecs.numcodecs import Delta
 
 filters = [Delta(dtype='int32')]
 compressors = zarr.codecs.BloscCodec(cname='zstd', clevel=1, shuffle=zarr.codecs.BloscShuffle.shuffle)
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		Correct the target bytes number for auto-chunking when auto-sharding.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		Fix a bug in the test suite that prevented stand-alone example scripts from being tested.
Original file line number	Diff line number	Diff line change
Expand Up		@@ -3,4 +3,3 @@ title: codec
		---

		::: zarr.abc.codec
		::: zarr.abc.numcodec
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		Zarr provides buffer classes for both the [cpu](./cpu.md) and [gpu](./gpu.md). Generic buffer functionality is also detailed below.

		::: zarr.buffer
Original file line number	Diff line number	Diff line change
Expand Up		@@ -3,5 +3,3 @@ title: codecs
		---

		::: zarr.codecs

		::: zarr.codecs.numcodecs
-Original file line number
+Diff line change
@@ Expand Up / @@ -52,7 +52,7 @@ conda install --channel conda-forge zarr @@
         A detailed guide for how to use Zarr-Python.
-    -   [:material-api:{ .lg .middle } __API Reference__](api/open.md)
+    -   [:material-api:{ .lg .middle } __API Reference__](api/zarr/open.md)
         ---
@@ Expand Down @@