chore: centralize development and CI verbs in just

.gitattributes

@@ -1,3 +1,9 @@
 *.py linguist-language=python
 *.ipynb linguist-documentation
 .git_archival.txt export-subst
+
+# just refuses to format a CRLF file, so `just just-check` would fail on a Windows
+# checkout with core.autocrlf=true before the contributor has changed anything.
+Justfile text eol=lf
+*/justfile text eol=lf
+packages/*/justfile text eol=lf

.github/labeler.yml

@@ -2,3 +2,21 @@ needs release notes:
   - all:
     - changed-files:
       - all-globs-to-all-files: '!changes/*.md'
+
+# Subpackage labels: a pull request whose changes all live under one package
+# directory gets that package's label, which .github/release.yml uses to keep
+# subpackage work out of the generated `zarr` release notes.
+zarr-metadata:
+  - all:
+    - changed-files:
+      - all-globs-to-all-files: 'packages/zarr-metadata/**'
+
+zarr-indexing:
+  - all:
+    - changed-files:
+      - all-globs-to-all-files: 'packages/zarr-indexing/**'
+
+zarr-http-server:
+  - all:
+    - changed-files:
+      - all-globs-to-all-files: 'packages/zarr-http-server/**'

.github/release.yml

@@ -0,0 +1,22 @@
+# Configuration for GitHub's "Generate release notes" button.
+#
+# The zarr-python repository also hosts the companion packages under packages/
+# (zarr-metadata, zarr-indexing, zarr-http-server), which have their own release
+# cadence, tags and changelogs. Pull requests that only touch a subpackage are
+# labelled by the labeler workflow (.github/labeler.yml) and excluded here, so a
+# `zarr` release lists only the changes that ship in `zarr`.
+changelog:
+  exclude:
+    labels:
+      - zarr-metadata
+      - zarr-indexing
+      - zarr-http-server
+    authors:
+      - pre-commit-ci[bot]
+  categories:
+    - title: Dependency updates
+      labels:
+        - dependencies
+    - title: What's Changed
+      labels:
+        - "*"

.github/workflows/check_changelogs.yml

@@ -22,16 +22,22 @@ jobs:
           persist-credentials: false
 
       - name: Install uv
-        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+
+      - name: Install just
+        uses: extractions/setup-crate@7577c1bdf2d95e6d65d532788f35ed79d4b1dda2 # v2.0.1
+        with:
+          repo: casey/just
+          version: 1.58.0
 
       - name: Check zarr-python changelog entries
-        run: uv run --no-sync python ci/check_changelog_entries.py
+        run: just check-changelogs
 
       - name: Check zarr-metadata changelog entries
-        run: uv run --no-sync python ci/check_changelog_entries.py packages/zarr-metadata/changes
+        run: just check-changelogs packages/zarr-metadata/changes
 
       - name: Check zarr-indexing changelog entries
-        run: uv run --no-sync python ci/check_changelog_entries.py packages/zarr-indexing/changes
+        run: just check-changelogs packages/zarr-indexing/changes
 
       - name: Check zarr-http-server changelog entries
-        run: uv run --no-sync python ci/check_changelog_entries.py packages/zarr-http-server/changes
+        run: just check-changelogs packages/zarr-http-server/changes

.github/workflows/codspeed.yml

@@ -31,10 +31,19 @@ jobs:
       uses: pypa/hatch@f647ed70d49adb885f53a27d1c7f5bdaeacf2c60
       with:
         version: '1.16.5'
+    # No interpreter is set up in this job on purpose. Benchmarks are only comparable
+    # across runs if the interpreter underneath them does not move: adding a pinned
+    # Python here measured a uniform ~13% slowdown on every benchmark, because hatch
+    # then built the environment on that interpreter instead of the runner's own.
+    - name: Install just
+      uses: extractions/setup-crate@7577c1bdf2d95e6d65d532788f35ed79d4b1dda2 # v2.0.1
+      with:
+        repo: casey/just
+        version: 1.58.0
     - name: Run the benchmarks
       uses: CodSpeedHQ/action@373d6868929f444bc08d901fd0eb0ad52a8875ea # v5.2.1
       env:
         ZARR_BENCHMARK_CLEAR_CACHE: '1'
       with:
           mode: walltime
-          run: hatch run test.py3.12-minimal:pytest tests/benchmarks --codspeed
+          run: HATCH_ENV=test.py3.12-minimal just benchmark-codspeed

.github/workflows/docs.yml

@@ -22,19 +22,23 @@ jobs:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
-      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
-      - run: uv sync --group docs
+      - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+      - name: Install just
+        uses: extractions/setup-crate@7577c1bdf2d95e6d65d532788f35ed79d4b1dda2 # v2.0.1
+        with:
+          repo: casey/just
+          version: 1.58.0
       # Fast source-level guards that need no built site, so they run before the (slower)
       # build for a quick failure: every public export is in the API reference, and no
       # docstring/Markdown carries reStructuredText markup that MkDocs won't render.
-      - run: uv run python ci/check_documented_exports.py docs/api
-      - run: uv run python ci/lint_docs.py
+      - run: just check-doc-exports
+      - run: just lint-docs
       # --strict turns warnings into errors, so a docs code block that fails to execute
       # at build time (e.g. a non-exec python fence disrupting a later exec="true" block)
       # fails CI instead of merging as a silent warning.
-      - run: uv run mkdocs build --strict
+      - run: just docs-build
         env:
           DISABLE_MKDOCS_2_WARNING: "true"
           NO_MKDOCS_2_WARNING: "true"
-      - run: uv run python ci/check_unlinked_types.py
+      - run: just check-doc-links
         continue-on-error: true

.github/workflows/downstream.yml

@@ -45,7 +45,7 @@ jobs:
           python-version: '3.13'
 
       - name: Install uv
-        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
 
       - name: Install xarray and test dependencies
         working-directory: xarray
@@ -59,18 +59,19 @@ jobs:
         working-directory: xarray
         run: uv pip install --no-deps ..
 
+      # Keep the branch override: syncing xarray would reinstall zarr from PyPI.
       - name: Show versions
         working-directory: xarray
         run: |
-          uv run python -c "
+          uv run --no-sync python -c "
           import zarr; print(f'zarr {zarr.__version__}')
           import xarray; print(f'xarray {xarray.__version__}')
           "
 
       - name: Run xarray zarr backend tests
         working-directory: xarray
         run: |
-          uv run python -m pytest --no-header -q \
+          uv run --no-sync python -m pytest --no-header -q \
             xarray/tests/test_backends.py \
             xarray/tests/test_backends_api.py \
             xarray/tests/test_backends_datatree.py
@@ -102,7 +103,7 @@ jobs:
           python-version: '3.13'
 
       - name: Install uv
-        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
 
       - name: Install numcodecs with test-zarr-main group
         working-directory: numcodecs

.github/workflows/gpu_test.yml

@@ -62,22 +62,29 @@ jobs:
         python-version: ${{ matrix.python-version }}
         cache: 'pip'
     - name: Install uv
-      uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+      uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
     - name: Install Hatch
       uses: pypa/hatch@f647ed70d49adb885f53a27d1c7f5bdaeacf2c60
       with:
         version: '1.16.5'
+    - name: Install just
+      uses: extractions/setup-crate@7577c1bdf2d95e6d65d532788f35ed79d4b1dda2 # v2.0.1
+      with:
+        repo: casey/just
+        version: 1.58.0
+    # Two names for the same environment on purpose: `just setup` builds whatever
+    # HATCH_ENV points at, while `just gpu` reads GPU_HATCH_ENV so that an
+    # ambient HATCH_ENV can never redirect `pytest -m gpu` into a CPU environment.
     - name: Set Up Hatch Env
       env:
         HATCH_ENV: gputest.py${{ matrix.python-version }}
       run: |
-        hatch env create "$HATCH_ENV"
-        hatch env run -e "$HATCH_ENV" list-env
+        just setup
     - name: Run Tests
       env:
-        HATCH_ENV: gputest.py${{ matrix.python-version }}
+        GPU_HATCH_ENV: gputest.py${{ matrix.python-version }}
       run: |
-        hatch env run --env "$HATCH_ENV" run-coverage
+        just gpu
 
     - name: Upload coverage
       uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f  # v7.0.0

.github/workflows/hypothesis.yaml

@@ -60,17 +60,21 @@ jobs:
         python-version: ${{ matrix.python-version }}
         cache: 'pip'
     - name: Install uv
-      uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+      uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
     - name: Install Hatch
       uses: pypa/hatch@f647ed70d49adb885f53a27d1c7f5bdaeacf2c60
       with:
         version: '1.16.5'
+    - name: Install just
+      uses: extractions/setup-crate@7577c1bdf2d95e6d65d532788f35ed79d4b1dda2 # v2.0.1
+      with:
+        repo: casey/just
+        version: 1.58.0
     - name: Set Up Hatch Env
       env:
         HATCH_ENV: test.py${{ matrix.python-version }}-${{ matrix.dependency-set }}
       run: |
-        hatch env create "$HATCH_ENV"
-        hatch env run -e "$HATCH_ENV" list-env
+        just setup
     # https://github.com/actions/cache/blob/main/tips-and-workarounds.md#update-a-cache
     - name: Restore cached hypothesis directory
       id: restore-hypothesis-cache
@@ -89,7 +93,7 @@ jobs:
         PYTEST_ADDOPTS: "--report-log=output-${{ matrix.python-version }}-log.jsonl"
       run: |
         echo "Using Hypothesis profile: $HYPOTHESIS_PROFILE"
-        hatch env run --env "$HATCH_ENV" run-hypothesis
+        just hypothesis
 
     # explicitly save the cache so it gets updated, also do this even if it fails.
     - name: Save cached hypothesis directory

.github/workflows/issue-metrics.yml

@@ -33,7 +33,7 @@ jobs:
         echo "last_month=$first_day..$last_day" >> "$GITHUB_ENV"
 
     - name: Run issue-metrics tool
-      uses: github-community-projects/issue-metrics@61084fa9599a62c7821f06602e180a42d1c7a205 # v5.0.1
+      uses: github-community-projects/issue-metrics@a7dc2fb675661e208d4fc6fa321a6b95fc4a06f9 # v5.0.2
       env:
         GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         SEARCH_QUERY: 'repo:zarr-developers/zarr-python is:issue created:${{ env.last_month }} -reason:"not planned"'

.github/workflows/lint.yml

@@ -27,7 +27,29 @@ jobs:
         with:
           python-version: "3.12"
       - name: Install uv
-        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
         with:
           enable-cache: true
-      - uses: j178/prek-action@4e14d07f9231acabce116ccfca13b13dd9755ece # v3.0.0
+      - name: Install just
+        uses: extractions/setup-crate@7577c1bdf2d95e6d65d532788f35ed79d4b1dda2 # v2.0.1
+        with:
+          repo: casey/just
+          version: 1.58.0
+      # `uvx prek` builds each hook's environment from scratch, so cache them the
+      # way the prek action used to. Keyed on the hook config: a new pinned rev or
+      # a new hook is exactly when the cached environments stop being valid.
+      - name: Cache prek hook environments
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        with:
+          path: ~/.cache/prek
+          # Justfile is hashed too: prek_version lives there, and a bumped prek
+          # must not restore a store built by the previous one. No restore-keys
+          # fallback for the same reason.
+          key: prek-${{ runner.os }}-${{ hashFiles('.pre-commit-config.yaml', 'Justfile') }}
+      - name: Lint
+        run: just lint
+      - name: Check justfile formatting
+        # After the linters, and never masking them: this is cosmetic, and a
+        # mis-formatted recipe should not cost someone their ruff/mypy results.
+        if: always()
+        run: just just-check

.github/workflows/nightly_wheels.yml

@@ -42,7 +42,7 @@ jobs:
         run: hatch build
 
       - name: Upload nightly wheels
-        uses: scientific-python/upload-nightly-action@e76cfec8a4611fd02808a801b0ff5a7d7c1b2d99
+        uses: scientific-python/upload-nightly-action@16fa02eacee1655195143de09f03676e60ef2bf5
         with:
           artifacts_path: dist
           anaconda_nightly_upload_token: ${{ secrets.ANACONDA_ORG_UPLOAD_TOKEN }}

.github/workflows/test.yml

@@ -66,21 +66,25 @@ jobs:
         python-version: ${{ matrix.python-version }}
         cache: 'pip'
     - name: Install uv
-      uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+      uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
     - name: Install Hatch
       run: python -m pip install hatch==1.16.5
+    - name: Install just
+      uses: extractions/setup-crate@7577c1bdf2d95e6d65d532788f35ed79d4b1dda2 # v2.0.1
+      with:
+        repo: casey/just
+        version: 1.58.0
     - name: Set Up Hatch Env
       env:
         HATCH_ENV: test.py${{ matrix.python-version }}-${{ matrix.dependency-set }}
       run: |
-        hatch env create "$HATCH_ENV"
-        hatch env run -e "$HATCH_ENV" list-env
+        just setup
     - name: Run Tests
       env:
         HYPOTHESIS_PROFILE: ci
         HATCH_ENV: test.py${{ matrix.python-version }}-${{ matrix.dependency-set }}
       run: |
-        hatch env run --env "$HATCH_ENV" run-coverage
+        just coverage
     - name: Upload coverage
       if: ${{ matrix.dependency-set == 'optional' && matrix.os == 'ubuntu-latest' }}
       uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0
@@ -115,20 +119,24 @@ jobs:
         python-version: ${{ matrix.python-version }}
         cache: 'pip'
     - name: Install uv
-      uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+      uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
     - name: Install Hatch
       run: python -m pip install hatch==1.16.5
+    - name: Install just
+      uses: extractions/setup-crate@7577c1bdf2d95e6d65d532788f35ed79d4b1dda2 # v2.0.1
+      with:
+        repo: casey/just
+        version: 1.58.0
     - name: Set Up Hatch Env
       env:
         HATCH_ENV: ${{ matrix.dependency-set }}
       run: |
-        hatch env create "$HATCH_ENV"
-        hatch env run -e "$HATCH_ENV" list-env
+        just setup
     - name: Run Tests
       env:
         HATCH_ENV: ${{ matrix.dependency-set }}
       run: |
-        hatch env run --env "$HATCH_ENV" run-coverage
+        just coverage
     - name: Upload coverage
       uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0
       with:
@@ -150,15 +158,20 @@ jobs:
         python-version: '3.13'
         cache: 'pip'
     - name: Install uv
-      uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+      uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
     - name: Install Hatch
       run: python -m pip install hatch==1.16.5
+    - name: Install just
+      uses: extractions/setup-crate@7577c1bdf2d95e6d65d532788f35ed79d4b1dda2 # v2.0.1
+      with:
+        repo: casey/just
+        version: 1.58.0
     - name: Set Up Hatch Env
       run: |
-        hatch run doctest:pip list
+        HATCH_ENV=doctest just setup
     - name: Run Tests
       run: |
-        hatch run doctest:test
+        just doctest
 
   benchmarks:
     name: Benchmark smoke test
@@ -174,14 +187,19 @@ jobs:
         python-version: '3.13'
         cache: 'pip'
     - name: Install uv
-      uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+      uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
     - name: Install Hatch
       run: python -m pip install hatch==1.16.5
+    - name: Install just
+      uses: extractions/setup-crate@7577c1bdf2d95e6d65d532788f35ed79d4b1dda2 # v2.0.1
+      with:
+        repo: casey/just
+        version: 1.58.0
     - name: Run Benchmarks
       env:
         ZARR_BENCHMARK_CLEAR_CACHE: '1'
       run: |
-        hatch env run --env "test.py3.13-minimal" run-benchmark
+        HATCH_ENV=test.py3.13-minimal just benchmark
 
   test-complete:
     name: Test complete