This is an automated email from the ASF dual-hosted git repository. github-merge-queue[bot] pushed a commit to branch gh-readonly-queue/main/pr-3638-5370b61638e205d7caf97889affe5da63aea9b16 in repository https://gitbox.apache.org/repos/asf/iceberg-rust.git
commit 9aa0b489b89944a88a21975b268b8e15de1eeae2 Author: Matt Butrovich <[email protected]> AuthorDate: Mon Nov 9 10:03:56 2026 +0000 docs: ask agents to consider public API maintenance (#3638) * docs: ask agents to consider public API maintenance * docs: lead public API guidance with justification --- AGENTS.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 5a1106e0b..f33279679 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -51,6 +51,23 @@ the code they describe or they are wrong. `make generate-public-api` to update each crate's `public-api.txt`, and check its diff for API growth. +## Public API + +Justify each new public item: check that it needs to be public and that it +fits the existing abstractions. Consider how it would be changed or removed +later, and prefer additive changes to breaking ones. Derives such as +`#[derive(Clone)]` count as public API. A type that needs table-scoped context +to construct gets an accessor on `Table` instead of a public `new()`, so new +parameters do not break callers. Prefer expandable types, such as structs and enums, for configuration +over adding parameters to a function, so options can grow without breaking +callers. + +Iceberg Java has a +[deprecation policy](https://github.com/apache/iceberg/blob/9203eaff9eb97fef9d1f5a3ef4460e8453adaed9/site/docs/contribute.md?plain=1#L142-L170) +that iceberg-rust has not adopted. Treat it as a reference for how long a +deprecation lasts, not as a rule. In a review, name every new or changed public +item and consider whether the change needs it. + ## Pull requests - Follow the PR template. Keep each section short: the problem, the
