From caaae75062b0d01ab9e11fcab595253fb7999e16 Mon Sep 17 00:00:00 2001 From: Paul Whalen Date: Sun, 1 Nov 2026 15:34:36 -0600 Subject: [PATCH 1/3] docs: add Claude rule for public API naming - Add .claude/rules/public-api.md: brief rules for mirroring the upstream Rust DataFusion API in the public Java surface (names, trait-to-interface shape, defaults, Java-only additions) Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_016TrBZwkmnnLujADyqc9nsF --- .claude/rules/public-api.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) create mode 100644 .claude/rules/public-api.md diff --git a/.claude/rules/public-api.md b/.claude/rules/public-api.md new file mode 100644 index 0000000..3c53fa7 --- /dev/null +++ b/.claude/rules/public-api.md @@ -0,0 +1,27 @@ +--- +paths: + - "core/src/main/java/org/apache/datafusion/**/*.java" +--- + +# Public API + +The public Java API mirrors the upstream Rust DataFusion API. Before adding a public type or method, +find its Rust counterpart and match it. + +- Use the Rust type, trait, method, and enum names: `snake_case` becomes `camelCase`, and enum + variants become `SCREAMING_SNAKE_CASE` (`JoinType::LeftSemi` becomes `JoinType.LEFT_SEMI`). +- Don't invent a Java-only name or type when Rust already has one. +- Rust traits map to Java interfaces. Optional trait methods are `default` methods. +- Covering only part of a Rust API is fine. When you leave something out, note the gap rather than + reshaping the API around it. +- Java-only additions are OK when they're needed for Java idioms (varargs, `Optional`). Say in the + Javadoc that the addition is Java-specific. +- Each public type's Javadoc names its Rust counterpart ("Mirrors DataFusion's {@code ScanArgs}"). + A docs.rs link is welcome but not required. +- A Java method whose Rust counterpart returns `Result` throws the unchecked `DataFusionException` + subclass matching the `DataFusionError` variant (`PlanException`, `ExecutionException`, …). Don't + add checked exceptions. +- Never expose JNI details in public signatures: no native handles, no `byte[]` marshalling + payloads, no codes for crossing the JNI boundary. Keep helpers like `toBytes()` package-private. +- A type that holds a native handle (`SessionContext`, `DataFrame`) implements `AutoCloseable`, and + `close()` frees the native resource. Plain value types and Java-implemented interfaces don't. From 483daad6ea97ba8687d75781cc6e45208288ffb6 Mon Sep 17 00:00:00 2001 From: Paul Whalen Date: Sat, 21 Nov 2026 13:22:48 -0600 Subject: [PATCH 2/3] docs: map Rust enums/structs to sealed types/records - Add rule to .claude/rules/public-api.md: data-carrying Rust enums become sealed interfaces with one record per variant; fieldless enums stay Java enums - Plain-data pub-field structs become records; builder-style structs stay final classes with builders - Document #[non_exhaustive] enums so callers add a default case Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_016TrBZvtSe6tvVYT6SVyJpo --- .claude/rules/public-api.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/.claude/rules/public-api.md b/.claude/rules/public-api.md index 3c53fa7..c74dccf 100644 --- a/.claude/rules/public-api.md +++ b/.claude/rules/public-api.md @@ -12,6 +12,16 @@ find its Rust counterpart and match it. variants become `SCREAMING_SNAKE_CASE` (`JoinType::LeftSemi` becomes `JoinType.LEFT_SEMI`). - Don't invent a Java-only name or type when Rust already has one. - Rust traits map to Java interfaces. Optional trait methods are `default` methods. +- Rust enums whose variants carry no data become Java `enum`s. Rust enums where any variant + carries data become a `sealed interface` named after the enum, with one nested `record` per + variant, named like the Rust variant in PascalCase (`Partitioning::Hash(exprs, n)` becomes + `record Hash(List exprs, int n)` implementing `Partitioning`, as `ColumnarValue` does). + Variants with no data become records with no components, not singleton constants. +- Rust structs whose fields are all `pub` and that are plain data become `record`s + (`ScalarFunctionArgs`). Structs with private fields and `new()`/`with_*` setters become final + classes with builders, since adding a record component breaks callers. +- If the Rust enum is `#[non_exhaustive]`, say so in the Javadoc: new variants may be added, so + callers should include a `default` case when they `switch` over it. - Covering only part of a Rust API is fine. When you leave something out, note the gap rather than reshaping the API around it. - Java-only additions are OK when they're needed for Java idioms (varargs, `Optional`). Say in the From fe2a6d0b2cd1cbd1b5210f646ba26f4acc70a990 Mon Sep 17 00:00:00 2001 From: Paul Whalen Date: Sat, 21 Nov 2026 13:23:40 -0600 Subject: [PATCH 3/3] docs: move public API rule to nested AGENTS.md - Move .claude/rules/public-api.md to core/src/main/java/org/apache/datafusion/AGENTS.md so any agent that honors nested AGENTS.md (Codex, Cursor, Copilot, etc.) picks it up when working in the public API package - Add sibling CLAUDE.md that imports @AGENTS.md for Claude Code - Add Apache license headers so both files pass RAT Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_016TrBZvtSe6tvVYT6SVyJpo --- .../main/java/org/apache/datafusion/AGENTS.md | 24 +++++++++++++++---- .../main/java/org/apache/datafusion/CLAUDE.md | 20 ++++++++++++++++ 2 files changed, 40 insertions(+), 4 deletions(-) rename .claude/rules/public-api.md => core/src/main/java/org/apache/datafusion/AGENTS.md (73%) create mode 100644 core/src/main/java/org/apache/datafusion/CLAUDE.md diff --git a/.claude/rules/public-api.md b/core/src/main/java/org/apache/datafusion/AGENTS.md similarity index 73% rename from .claude/rules/public-api.md rename to core/src/main/java/org/apache/datafusion/AGENTS.md index c74dccf..e811aed 100644 --- a/.claude/rules/public-api.md +++ b/core/src/main/java/org/apache/datafusion/AGENTS.md @@ -1,10 +1,26 @@ ---- -paths: - - "core/src/main/java/org/apache/datafusion/**/*.java" ---- + # Public API +These instructions apply to the public Java API in this package and its subpackages. + The public Java API mirrors the upstream Rust DataFusion API. Before adding a public type or method, find its Rust counterpart and match it. diff --git a/core/src/main/java/org/apache/datafusion/CLAUDE.md b/core/src/main/java/org/apache/datafusion/CLAUDE.md new file mode 100644 index 0000000..355a07e --- /dev/null +++ b/core/src/main/java/org/apache/datafusion/CLAUDE.md @@ -0,0 +1,20 @@ + + +@AGENTS.md