Skip to content

docs: add agent rules for public API naming - #1

Draft
pgwhalen wants to merge 3 commits into
mainfrom
public-api-rule
Draft

pgwhalen wants to merge 3 commits into
mainfrom
public-api-rule

Conversation

@pgwhalen

@pgwhalen pgwhalen commented Nov 1, 2026 •

Copy link
Copy Markdown
Owner

Adds core/src/main/java/org/apache/datafusion/AGENTS.md, agent instructions for keeping the public Java API in line with the upstream Rust DataFusion API. Using a nested AGENTS.md means any agent that reads AGENTS.md (Codex, Cursor, Copilot, etc.) picks the rules up when it works in the public API package. A sibling CLAUDE.md imports it (@AGENTS.md) for Claude Code, which doesn't read AGENTS.md itself.

  • Use the Rust type, method, and enum names; don't invent Java-only names when Rust has one.
  • Rust traits map to Java interfaces; optional trait methods are default methods.
  • Fieldless Rust enums become Java enums; data-carrying Rust enums become a sealed interface with one record per variant. Plain-data pub structs become records; builder-style structs stay classes with builders. #[non_exhaustive] enums are documented as such.
  • Java-only additions are allowed for Java idioms but must be documented as Java-specific.
  • Rust Result errors map to the matching unchecked DataFusionException subclass.
  • No JNI details (native handles, byte[] payloads, boundary codes) in public signatures.

Both files carry the Apache license header and pass apache-rat-plugin:check.

🤖 Generated with Claude Code

https://claude.ai/code/session_016TrBZvtSe6tvVYT6SVyJpo

- 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 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016TrBZwkmnnLujADyqc9nsF
pgwhalen and others added 2 commits November 21, 2026 13:22
- 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 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016TrBZvtSe6tvVYT6SVyJpo
- 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 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016TrBZvtSe6tvVYT6SVyJpo
@pgwhalen pgwhalen changed the title docs: add Claude rule for public API naming docs: add agent rules for public API naming Nov 21, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant