Skip to content

AGENTS.md

Latest commit

 

History

History
85 lines (71 loc) · 3.91 KB

AGENTS.md

File metadata and controls

85 lines (71 loc) · 3.91 KB
Raw

Apache Iceberg Rust — Agent Instructions

This file provides repository-specific guidance for automated agents working in this repository.

Comments, docs, and diff scope

Default to no comment. Leave existing comments as they are unless you change the code they describe or they are wrong.

  • Comment only what the code cannot say: invariants, non-obvious constraints, links to external behavior. Do not restate the code.
  • Do not describe how the code changed or explain review history ("previously", "instead of", "unlike X"). Put that in the commit message or PR description.
  • Public items get a one-line doc summary of what they do for the caller, not how. Expand only for contract the caller must know, such as the errors it returns (# Errors) or when it panics (# Panics).
  • Test names say what they check. Do not narrate asserts.
  • Cover the edge cases and error paths the change adds, not only the happy path.
  • Build the expected value and assert equality with it, rather than checking fields one at a time.
  • Do not add tests that duplicate existing coverage.
  • Do not rename, reformat, refactor, or reorder code unrelated to the change. A bug fix does not carry an API redesign.
  • Reuse existing helpers, types, and test fixtures (such as TableTestFixture) before adding new ones. Use arrow-rs kernels instead of reimplementing them.
  • Use the narrowest visibility that works. Make items pub only when they are part of the API the change intends to expose. Run 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 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 approach, and anything a reviewer would not guess from the diff. In AI Disclosure, name the areas of uncertainty or assumptions a reviewer should focus on.
  • Do not restate the diff: no file-by-file walkthroughs, per-function summaries, or "changes made" checklists.

Security Model

When assessing potential vulnerabilities or calibrating automated security findings, use SECURITY-THREAT-MODEL.md as the authoritative detailed description of this repository's security boundaries, trust assumptions, and non-boundaries.