From f9eecbc51a45e8c971566593683376847c6f4be2 Mon Sep 17 00:00:00 2001 From: Norman Rzepka Date: Wed, 9 Sep 2026 17:55:37 +0200 Subject: [PATCH] Add agent instructions, changelog and PR template Adds contributor- and agent-facing documentation that the repository was missing: - CLAUDE.md with the project layout, Maven commands, test prerequisites and code conventions (IntelliJ formatting, Java 8 source compatibility). - AGENTS.md pointing at CLAUDE.md so agents following either convention find the same instructions. - CHANGELOG.md covering every release from 0.0.1 to 0.3.0, reconstructed from the commit history between tags. - A pull request template with a checklist mirroring the conventions documented in CLAUDE.md. Co-Authored-By: Claude Opus 5 --- .github/pull_request_template.md | 13 +++ AGENTS.md | 37 ++++++++ CHANGELOG.md | 149 +++++++++++++++++++++++++++++++ CLAUDE.md | 1 + 4 files changed, 200 insertions(+) create mode 100644 .github/pull_request_template.md create mode 100644 AGENTS.md create mode 100644 CHANGELOG.md create mode 100644 CLAUDE.md diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 00000000..dc66c1c0 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,13 @@ +## Description + + + +## Related issues + + + +## Checklist + +- [ ] Added tests for the new behavior or bug fix +- [ ] Added an entry to [CHANGELOG.md](../CHANGELOG.md) under `Unreleased` +- [ ] Updated [USERGUIDE.md](../USERGUIDE.md) / [USERGUIDE-OME-ZARR.md](../USERGUIDE-OME-ZARR.md) if the public API changed diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..1163010c --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,37 @@ +# AGENTS.md + +`zarr-java` (`dev.zarr:zarr-java`) is a Java implementation of the Zarr v2 and v3 +array storage specs, plus experimental OME-Zarr support. Public API entry points +are `dev.zarr.zarrjava.v2.{Array,Group}` and `dev.zarr.zarrjava.v3.{Array,Group}`. + +- Build: Maven, compiled with `maven.compiler.release=8` (build with JDK 11). +- Arrays are backed by `ucar.ma2.Array` (netCDF-Java). +- Metadata is (de)serialized with Jackson. + +## Layout + +- `core/` — version-agnostic base types (`Array`, `Group`, `ArrayMetadata`, + `DataType`, `Attributes`), shared codecs (`core/codec`) and chunk key encodings. +- `v2/`, `v3/` — spec-version-specific metadata, codecs and chunk grids. +- `store/` — `Store` backends: `FilesystemStore`, `HttpStore`, `S3Store`, + `MemoryStore`, `ZipStore`/`ReadOnlyZipStore`/`BufferedZipStore`. Keys are + addressed through `StoreHandle`. +- `experimental/ome/` — OME-Zarr (NGFF) v0.4 / v0.5 / v0.6 metadata models. +- `cli/` — command line wrapper. +- `utils/` — indexing helpers, notably `IndexingUtils`. + +## Conventions + +- IntelliJ IDEA default Java formatting; run `Reformat Code` and + `Optimize Imports` before submitting changes. +- New user-visible changes go in [CHANGELOG.md](CHANGELOG.md) under `Unreleased`. +- User-facing documentation lives in [USERGUIDE.md](USERGUIDE.md) and + [USERGUIDE-OME-ZARR.md](USERGUIDE-OME-ZARR.md); update them alongside API changes. +- When writing code comments, keep them short and concise, do not reference other code or previous behavior. + +## Pull requests + +- After opening a PR, make sure to add the PR number to added changelog entries, e.g. [#103](https://github.com/zarr-developers/zarr-java/pull/103). +- Use the PR template at .github/pull_request_template.md. +- Keep your summaries short and to the point. +- When adding comments or replies to PRs, always mention that Claude wrote them. \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 00000000..3e0d8c9a --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,149 @@ +# Changelog + +All notable changes to zarr-java are documented in this file. + +The format is loosely based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [Unreleased] + +## [0.3.0] - 2026-09-09 + +### Added + +- Support for open-ended byte ranges in `getInputStream` [#103](https://github.com/zarr-developers/zarr-java/pull/103). +- `cast_value` codec [#83](https://github.com/zarr-developers/zarr-java/pull/83). +- `gzip` codec for Zarr v2 arrays [#98](https://github.com/zarr-developers/zarr-java/pull/98). + +### Fixed + +- Fail loudly instead of silently on unreadable ZIP stores [#103](https://github.com/zarr-developers/zarr-java/pull/103). +- Accept a `shuffle` value of `-1` in Zarr v2 blosc metadata [#102](https://github.com/zarr-developers/zarr-java/pull/102). +- Logging of unknown fields in OME metadata is less severe [#75](https://github.com/zarr-developers/zarr-java/pull/75). + +## [0.2.0] - 2026-07-29 + +### Added + +- `reshape` codec. + +### Changed + +- Removed unnecessary `resolveOutputShape` calls. + +## [0.1.3] - 2026-05-04 + +### Fixed + +- Blosc `shuffle` handling; bumped `blosc-java`. +- The shaded JAR is attached as a classifier instead of replacing the main artifact. + +## [0.1.2] - 2026-03-31 + +### Added + +- Command line wrapper [#45](https://github.com/zarr-developers/zarr-java/pull/45). + +### Changed + +- `CodecBuilder` accepts a compression `level` for the gzip and zstd codecs [#69](https://github.com/zarr-developers/zarr-java/pull/69). +- OME-Zarr follow-up improvements [#68](https://github.com/zarr-developers/zarr-java/pull/68). + +## [0.1.1] - 2026-03-23 + +### Added + +- Experimental OME-Zarr (NGFF) support [#66](https://github.com/zarr-developers/zarr-java/pull/66). + +## [0.1.0] - 2026-03-05 + +### Added + +- User guide and expanded documentation [#55](https://github.com/zarr-developers/zarr-java/pull/55). +- Big-endian data types for Zarr v2 [#60](https://github.com/zarr-developers/zarr-java/pull/60). +- Retries for HTTP requests [#62](https://github.com/zarr-developers/zarr-java/pull/62). +- Parallel decoding in `ShardingIndexedCodec` [#61](https://github.com/zarr-developers/zarr-java/pull/61). +- Chunk data is deleted when an array is resized, plus additional tests [#49](https://github.com/zarr-developers/zarr-java/pull/49). + +### Changed + +- `Array.read` takes `long` shape arguments and store requests are validated [#54](https://github.com/zarr-developers/zarr-java/pull/54). +- Replaced a `ByteBuffer.array()` call [#58](https://github.com/zarr-developers/zarr-java/pull/58). + +### Fixed + +- Race condition in `ShardingIndexedCodec` during parallel encoding [#61](https://github.com/zarr-developers/zarr-java/pull/61). +- Removed an unnecessary double store read in sharding [#57](https://github.com/zarr-developers/zarr-java/pull/57). +- `zstd` in combination with sharding [#56](https://github.com/zarr-developers/zarr-java/pull/56). + +## [0.0.10] - 2026-01-30 + +### Added + +- `ZipStore` [#37](https://github.com/zarr-developers/zarr-java/pull/37). +- `MemoryStore` [#36](https://github.com/zarr-developers/zarr-java/pull/36). +- Default chunk shape calculation for v2 and v3 arrays [#50](https://github.com/zarr-developers/zarr-java/pull/50). + +### Fixed + +- `IndexingUtils.computeProjection` [#48](https://github.com/zarr-developers/zarr-java/pull/48). +- A missing `configuration` key for `chunkKeyEncoding` is accepted [#42](https://github.com/zarr-developers/zarr-java/pull/42). + +## 0.0.6 – 0.0.9 - 2025-12-04 + +Release-process fixes only; no library changes. + +## [0.0.5] - 2025-11-22 + +### Added + +- Zarr v2 core features: arrays, groups and attributes [#22](https://github.com/zarr-developers/zarr-java/pull/22), [#25](https://github.com/zarr-developers/zarr-java/pull/25), [#28](https://github.com/zarr-developers/zarr-java/pull/28). +- Support for arrays smaller than their chunk size [#9](https://github.com/zarr-developers/zarr-java/pull/9). +- `storageTransformers` metadata attribute; array creation fails on non-empty storage transformers. +- Reading a missing chunk returns a chunk filled with the fill value. + +### Changed + +- Dependency version updates [#26](https://github.com/zarr-developers/zarr-java/pull/26). +- Clearer exception when requested data lies outside the array's domain. + +### Fixed + +- Codecs without a `configuration` entry [#34](https://github.com/zarr-developers/zarr-java/pull/34). +- `S3Store.exists` catches `NoSuchKeyException` [#31](https://github.com/zarr-developers/zarr-java/pull/31). + +## [0.0.4] - 2024-08-22 + +Version bump only. + +## [0.0.3] - 2024-08-15 + +### Added + +- Validation of sharding bounds and chunk bounds during metadata creation. + +## [0.0.2] - 2024-07-04 + +### Changed + +- Artifacts are published to Maven Central; sources are compiled with JDK 11 + targeting Java 8. +- The blosc dependency is pulled from Maven instead of being downloaded manually. + +## [0.0.1] - 2024-07-04 + +Initial release with Zarr v3 support. + +[Unreleased]: https://github.com/zarr-developers/zarr-java/compare/0.3.0...HEAD +[0.3.0]: https://github.com/zarr-developers/zarr-java/compare/0.2.0...0.3.0 +[0.2.0]: https://github.com/zarr-developers/zarr-java/compare/0.1.3...0.2.0 +[0.1.3]: https://github.com/zarr-developers/zarr-java/compare/0.1.2...0.1.3 +[0.1.2]: https://github.com/zarr-developers/zarr-java/compare/0.1.1...0.1.2 +[0.1.1]: https://github.com/zarr-developers/zarr-java/compare/0.1.0...0.1.1 +[0.1.0]: https://github.com/zarr-developers/zarr-java/compare/0.0.10...0.1.0 +[0.0.10]: https://github.com/zarr-developers/zarr-java/compare/0.0.9...0.0.10 +[0.0.5]: https://github.com/zarr-developers/zarr-java/compare/0.0.4...0.0.5 +[0.0.4]: https://github.com/zarr-developers/zarr-java/compare/0.0.3...0.0.4 +[0.0.3]: https://github.com/zarr-developers/zarr-java/compare/0.0.2...0.0.3 +[0.0.2]: https://github.com/zarr-developers/zarr-java/compare/0.0.1...0.0.2 +[0.0.1]: https://github.com/zarr-developers/zarr-java/releases/tag/0.0.1 diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..eef4bd20 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md \ No newline at end of file