From 6693f161754280e833141808af6085ebdb9e1fdb Mon Sep 17 00:00:00 2001 From: Fokko Driesprong Date: Wed, 18 Nov 2026 21:58:01 +0100 Subject: [PATCH 1/2] Point agents at the Iceberg spec and Java reference implementation Agents had no instruction to validate behavior against the spec, or to fall back to the Java implementation where the spec is ambiguous. --- AGENTS.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 3dc1d79c72..3e8d11ce90 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -52,6 +52,13 @@ lives under `pyiceberg/`, organized by concern rather than by engine: - Use domain-specific exceptions from pyiceberg/exceptions.py for Iceberg-specific error conditions. For invalid arguments/values, ValueError is acceptable. Don't raise bare Exception. - Comments should be succinct and follow the same style of comments found in the rest of the codebase. +### Spec Compliance + + +- The [Iceberg spec](https://github.com/apache/iceberg/blob/main/format/spec.md) is the source of truth. Check changes to metadata, manifests, schemas, partitioning, transforms, or the commit path against it, and cite the relevant section when behavior is non-obvious. + +- Where the spec is ambiguous or silent, follow the [Java reference implementation](https://github.com/apache/iceberg). Deviations from Java need a justification in the PR. + ### Dependencies - Large/integration libraries must be **optional extras** in `pyproject.toml`, not core `dependencies`. From 41e74a524cf5cb5819c84f64b00cfa42e421c0b7 Mon Sep 17 00:00:00 2001 From: Fokko Driesprong Date: Wed, 18 Nov 2026 22:53:26 +0100 Subject: [PATCH 2/2] Address review: drop link-check disables, add REST spec, broaden Java guidance Co-authored-by: Isaac --- AGENTS.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 3e8d11ce90..7493fdc6f2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -54,10 +54,9 @@ lives under `pyiceberg/`, organized by concern rather than by engine: ### Spec Compliance - - The [Iceberg spec](https://github.com/apache/iceberg/blob/main/format/spec.md) is the source of truth. Check changes to metadata, manifests, schemas, partitioning, transforms, or the commit path against it, and cite the relevant section when behavior is non-obvious. - -- Where the spec is ambiguous or silent, follow the [Java reference implementation](https://github.com/apache/iceberg). Deviations from Java need a justification in the PR. +- Changes to the REST catalog (`pyiceberg/catalog/rest/`) must follow the [REST catalog OpenAPI spec](https://github.com/apache/iceberg/blob/main/open-api/rest-catalog-open-api.yaml). +- Check every change, including catalog work, against the [Java reference implementation](https://github.com/apache/iceberg). Where the spec is ambiguous or silent, follow Java. Deviations from Java need a justification in the PR. ### Dependencies