diff --git a/AGENTS.md b/AGENTS.md index 3dc1d79c72..7493fdc6f2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -52,6 +52,12 @@ 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. +- 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 - Large/integration libraries must be **optional extras** in `pyproject.toml`, not core `dependencies`.