fix: match v* when extracting a zarr version from git tags

[d-v-b]

This is high priority, as failing to apply this fix before our next release will ship a zarr that pretends to be much younger than it is.

TODO:

• Add unit tests and/or doctests in docstrings
• Add docstrings and API docs for any new/modified user-facing classes and functions
• New/modified features documented in docs/user-guide/*.md
• Changes documented as a new file in changes/
• GitHub Actions have all passed
• Test coverage is 100% (Codecov passes)

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.39%. Comparing base (27abff2) to head (b34b540).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #3994   +/-   ##
=======================================
  Coverage   93.39%   93.39%           
=======================================
  Files          88       88           
  Lines       11839    11839           
=======================================
  Hits        11057    11057           
  Misses        782      782           

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[d-v-b]

closes #3993

[maxrjones]

Is there a way to test this in the CI?

[maxrjones]

Is there a way to test this in the CI?

Seems like we could use the test structure that numcodecs uses in https://github.com/zarr-developers/zarr-python/actions/runs/26187664671/job/77047478983?pr=3992. Could you please add a test @d-v-b?

[d-v-b]

The problem here is that zarr derives its version from the wrong git tag at runtime. That numcodecs test job fails because no numcodecs tests are collected, because the entire test file is skipped on zarr versions < 3.1.3: https://github.com/zarr-developers/numcodecs/blob/fa92ee7ec031479e48098f57604fed313cc72986/tests/test_zarr3.py#L10

I don't think we want to codify this behavior -- failing if zarr's runtime version is < "3.1.3" -- in a test.

[d-v-b]

an automated test would be valuable if we were planning on making a lot of changes to our git tag conventions. but I don't think we are, so I'm not really sure a test makes sense here, vs manually checking that the zarr version is correctly inferred on this branch.

[d-v-b]

uv run python -c "import zarr; print(zarr.__version__)"

main:

0.2.0

this branch:

3.2.2.dev30+gdc5e1825

[maxrjones]

I generally think we should avoid minimalism in testing and manual testing whenever possible. I think it's not good that we only caught this error because we were running numcodec's tests in our CI. That suggests to me that our version testing infrastructure is insufficient. Testing for some reasonable version structure like a regex similar v3.*.* seems like a small addition with few downsides that would prevent future issues and rarely need changing. But I'm not going to block merging on that.

[d-v-b]

Testing for some reasonable version structure like a regex similar v3.. seems like a small addition with few downsides that would prevent future issues and rarely need changing. But I'm not going to block merging on that.

what specific test do you propose? Testing for 3.x would break when we release 4.x we could e.g. test that the current version is greater than the previous version, but that would break if we choose a different versioning convention.

[d-v-b]

@maxrjones have a look, this is a test that would have failed without the fix in this PR.

I'm not really sure it's worth the code, and it feels brittle because it requires parsing our pyproject.toml file. Open to ideas for simplifying this and / or finding a better way to to test the invariant (that tags starting with v, and not tags starting with zarr-metadata-v, contribute to the output of git describe, given the extra parameters to that command defined in pyproject.toml)

[maxrjones]

what about the suggestion in #3994 (comment)? It seems much less fragile and would catch bugs of this class

[maxrjones]

what specific test do you propose?

"""Sanity check that ``zarr.__version__`` looks like a v3-or-newer release.
 
Background: zarr-python derives its version from ``git describe`` via
hatch-vcs. The repo also publishes a separate ``zarr-metadata`` subpackage
that uses ``zarr_metadata-v*`` tags. Without the ``--match v*`` filter in
``[tool.hatch] version.raw-options.git_describe_command``, ``git describe``
walks back to those subpackage tags and reports a version like ``0.2.0`` for
a from-source build of zarr-python itself — see
https://github.com/zarr-developers/zarr-python/pull/3994.
 
This test catches that class of regression: anything that makes zarr-python
report a version lower than the v3 release line. When 4.0 is released,
bump the floor; that's a deliberate, one-line edit at a planned boundary.
"""
 
from __future__ import annotations
 
from packaging.version import Version
 
import zarr
 
 
def test_version_is_v3_or_newer() -> None:
    # Use packaging.Version so we transparently handle hatch-vcs dev suffixes
    # like "3.2.2.dev30+gdc5e1825" that appear on any source build past the
    # latest v* tag — Version.major returns 3 for that string.
    parsed = Version(zarr.__version__)
    assert parsed.major >= 3, (
        f"zarr.__version__={zarr.__version__!r} is not on the v3 (or newer) "
        f"release line. If this fires on a from-source build, check that "
        f"[tool.hatch] version.raw-options.git_describe_command in "
        f"pyproject.toml still includes ``--match v*`` so the "
        f"``zarr_metadata-v*`` subpackage tags are excluded. See PR #3994."
    )

[d-v-b]

what specific test do you propose?

"""Sanity check that ``zarr.__version__`` looks like a v3-or-newer release.
 
Background: zarr-python derives its version from ``git describe`` via
hatch-vcs. The repo also publishes a separate ``zarr-metadata`` subpackage
that uses ``zarr_metadata-v*`` tags. Without the ``--match v*`` filter in
``[tool.hatch] version.raw-options.git_describe_command``, ``git describe``
walks back to those subpackage tags and reports a version like ``0.2.0`` for
a from-source build of zarr-python itself — see
https://github.com/zarr-developers/zarr-python/pull/3994.
 
This test catches that class of regression: anything that makes zarr-python
report a version lower than the v3 release line. When 4.0 is released,
bump the floor; that's a deliberate, one-line edit at a planned boundary.
"""
 
from __future__ import annotations
 
from packaging.version import Version
 
import zarr
 
 
def test_version_is_v3_or_newer() -> None:
    # Use packaging.Version so we transparently handle hatch-vcs dev suffixes
    # like "3.2.2.dev30+gdc5e1825" that appear on any source build past the
    # latest v* tag — Version.major returns 3 for that string.
    parsed = Version(zarr.__version__)
    assert parsed.major >= 3, (
        f"zarr.__version__={zarr.__version__!r} is not on the v3 (or newer) "
        f"release line. If this fires on a from-source build, check that "
        f"[tool.hatch] version.raw-options.git_describe_command in "
        f"pyproject.toml still includes ``--match v*`` so the "
        f"``zarr_metadata-v*`` subpackage tags are excluded. See PR #3994."
    )

I'm fine taking this but just not that it will fail to catch the case where the tagged version of a subpackage is greater than zarr's version, and that subpackage's git tag interferes with zarr's version inference. It will also fail if we ever change our versioning scheme.

[maxrjones]

I'm fine taking this but just not that it will fail to catch the case where the tagged version of a subpackage is greater than zarr's version, and that subpackage's git tag interferes with zarr's version inference.

yeah, I think that's an ok risk.

It will also fail if we ever change our versioning scheme.

I think this is a good thing; it means our change in versioning scheme must be intentional and involve updating the test.

[d-v-b]

I'm fine taking this but just not that it will fail to catch the case where the tagged version of a subpackage is greater than zarr's version, and that subpackage's git tag interferes with zarr's version inference.

yeah, I think that's an ok risk.

It will also fail if we ever change our versioning scheme.

I think this is a good thing; it means our change in versioning scheme must be intentional and involve updating the test.

to be more precise, it might fail if we change our versioning scheme, but it also might not, because it doesn't test for a specific versioning scheme, just that whatever version we use sorts after "3". But I think this risk is pretty low, so I'm going to merge this pr with this test. Thanks for your help max!