Skip to content

Use a release checklist and narrative announcement for breaking changes #3209

Closed

Description

@maxrjones

I'd like to propose some improvements to Zarr-Python's release process based on a retro of the release of Zarr Python 3.0.9.

What happened

What we can do better in the future

  • Explicitly test against downstream libraries prior to releases
    • Short term: Add instructions on checking the upstream CI workflows of downstream dependencies to a release-checklist
    • Long term: Consider adding CI to zarr-python's repository that runs downstream-libraries' test suites
  • Label bug fixes that involve breakages (e.g., Create read only copy if needed when opening a store path #3156) in the changelog
  • Put out a narrative announcement in addition to the more concise release notes any time there is a breaking change. I found myself repeating a lot last week something along the lines of "I'm sorry this is inconvenient and know that the with_read_only() compromise is not great. It was a necessary short-term fix to protect against data deletion" and think it would have been better to have a short narrative at the top of https://zarr.readthedocs.io/en/stable/release-notes.html#id2 to point to.

Activity

  1. d-v-b commented on Jul 7, 2025

    @d-v-b
    Contributor

    thanks for this writeup max!

    Big +1 to more narrative communication. I think this can go a long way towards explaining why stuff is happening, especially when there's a historical context for it.

    I'd love to see some automated downstream testing as part of our CI. Does anyone have ideas for implementing this, and / or suggestions for packages to consider testing against (xarray is evidently a good test target)?

  2. dcherian commented on Jul 11, 2025

    @dcherian
    Contributor
  3. maxrjones commented on Nov 3, 2025

    @maxrjones
    MemberAuthor

    The release checklist was added in #3210 and is being used for various releases.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions