[ZEPPELIN-6405] Add AGENTS.md for AI coding agent guidance by jongyoul · Pull Request #5187 · apache/zeppelin

jongyoul · 2026-03-18T02:15:35Z

Summary

Add comprehensive AGENTS.md following the open standard to help AI coding agents understand and work effectively with the Zeppelin codebase
Covers module architecture, server-interpreter Thrift IPC communication, plugin system with custom classloading, reflection patterns, interpreter lifecycle, and contributing guide
Build/test instructions kept concise; focus on deep architectural context

Test plan

Verify AGENTS.md renders correctly on GitHub
Verify RAT license check passes (./mvnw clean org.apache.rat:apache-rat-plugin:check -Prat)

Add comprehensive AGENTS.md following the open standard to help AI coding agents understand and work effectively with the Zeppelin codebase. Includes module architecture, server-interpreter Thrift IPC communication details, plugin system with custom classloading, reflection patterns, interpreter lifecycle, and contributing guide. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

… exclusion Add the standard ASF license header to AGENTS.md instead of excluding it from the RAT license check. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…s, and config map; add AI agent dirs to .gitignore AGENTS.md additions: - Build Gotchas: shaded JAR rebuild chain, module build order - Configuration Files: conf/ file roles and template relationship - Module Boundaries: where new code should go - Thrift Code Generation: genthrift.sh workflow, generated files in git - REST API Pattern: AbstractRestApi, JsonResponse, @ZeppelinApi conventions .gitignore additions: - AI coding agent personal config directories (CLAUDE.md, GEMINI.md, .claude/, .gemini/, .codex/, .cursor/, .windsurf/, .cline/, .continue/, .aider*, .augment/, .amazonq/, .junie/, .goose/, .roo/) - AGENTS.md remains shared and tracked in git Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Copilot

Pull request overview

Adds an AGENTS.md guide (per the agents-md standard) to document Apache Zeppelin’s architecture and contributor workflows for AI coding agents, plus updates .gitignore to exclude agent-specific local config files.

Changes:

Introduces AGENTS.md with build/test commands and deep architectural context (modules, Thrift IPC, plugin/classloading, interpreter lifecycle).
Adds .gitignore entries for various AI-agent local config files/directories to keep them untracked.

Reviewed changes

Copilot reviewed 1 out of 2 changed files in this pull request and generated 8 comments.

File	Description
AGENTS.md	New AI-agent guidance doc covering build/test workflow and Zeppelin architecture details.
.gitignore	Ignores common AI-agent local configuration files/directories.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-04T05:49:29Z

AGENTS.md

+./mvnw clean package -pl zeppelin-server -DskipTests
+
+# Run module tests
+./mvnw test -pl zeppelin-zengine
+
+# Run single test class/method
+./mvnw test -pl zeppelin-server -Dtest=NotebookServerTest
+./mvnw test -pl zeppelin-server -Dtest=NotebookServerTest#testMethod


The module-scoped Maven commands here omit --am (also-make). From a clean checkout, ./mvnw clean package -pl zeppelin-server may fail because upstream reactor modules aren’t built/installed. Consider updating these examples to include --am (or note that a prior full build/install is required), consistent with docs/development/contribution/useful_developer_tools.md which uses --am for partial builds.

Suggested change

./mvnw clean package -pl zeppelin-server -DskipTests

# Run module tests

./mvnw test -pl zeppelin-zengine

# Run single test class/method

./mvnw test -pl zeppelin-server -Dtest=NotebookServerTest

./mvnw test -pl zeppelin-server -Dtest=NotebookServerTest#testMethod

./mvnw clean package -pl zeppelin-server --am -DskipTests

# Run module tests

./mvnw test -pl zeppelin-zengine --am

# Run single test class/method

./mvnw test -pl zeppelin-server --am -Dtest=NotebookServerTest

./mvnw test -pl zeppelin-server --am -Dtest=NotebookServerTest#testMethod

Copilot · 2026-04-04T05:49:30Z

AGENTS.md

+| Module | Description |
+|--------|-------------|
+| `spark/` | Apache Spark (Scala/Python/R/SQL) — most complex interpreter |


This Markdown table starts with || (double leading pipe), which renders as an extra empty column in GitHub-flavored Markdown. Use a single leading | for each row (or omit leading pipes consistently) to avoid an unintended blank column.

Copilot · 2026-04-04T05:49:30Z

AGENTS.md

+| File | Purpose |
+|------|---------|
+| `conf/zeppelin-site.xml` | Main server config (port, SSL, notebook storage, interpreter settings). Copy from `.template` |
+| `conf/zeppelin-env.sh` | Shell environment (JAVA_OPTS, memory, Spark master). Copy from `.template` |
+| `conf/shiro.ini` | Authentication/authorization (users, roles, LDAP, Kerberos, PAM). Copy from `.template` |
+| `conf/interpreter.json` | Runtime interpreter settings — **auto-generated**, do not edit manually |
+| `conf/log4j2.properties` | Logging configuration |
+| `conf/interpreter-list` | Static list of available interpreters with Maven coordinates |
+| `{interpreter}/resources/interpreter-setting.json` | Interpreter defaults (build-time, bundled in JAR) |


This Markdown table uses || at the start of rows, which creates an extra empty column when rendered on GitHub. Replace || with a single leading | (or remove the leading pipes) so the table renders with the intended columns.

Copilot · 2026-04-04T05:49:30Z

AGENTS.md

+| If the code... | Put it in |
+|----------------|-----------|
+| Is a base interface/class that all interpreters need | `zeppelin-interpreter` |
+| Handles notebook state, interpreter lifecycle, scheduling, search | `zeppelin-zengine` |
+| Is a REST endpoint, WebSocket handler, or authentication realm | `zeppelin-server` |
+| Is specific to one backend (Spark, Flink, JDBC, etc.) | That interpreter's module |
+| Is a new way to launch interpreter processes | `zeppelin-plugins/launcher/` |
+| Is a new notebook storage backend | `zeppelin-plugins/notebookrepo/` |


This table’s rows begin with ||, which causes an extra empty column in GitHub’s Markdown renderer. Update the table rows to start with a single | (or no leading pipe) for correct rendering.

Copilot · 2026-04-04T05:49:30Z

AGENTS.md

+| perNote | perUser | Behavior |
+|---------|---------|----------|
+| `shared` | `shared` | All users share one process (default) |
+| `scoped` | `shared` | Separate interpreter instance per note, same process |
+| `isolated` | `shared` | Separate process per note |
+| `shared` | `scoped` | Separate interpreter instance per user, same process |
+| `shared` | `isolated` | Separate process per user |
+| `scoped` | `scoped` | Separate instance per user+note |
+| `isolated` | `isolated` | Separate process per user+note (full isolation) |


This table header uses || at the start of the row, which renders as an unintended empty first column on GitHub. Adjust the table syntax (single leading | or none) so the columns line up as intended.

Copilot · 2026-04-04T05:49:30Z

AGENTS.md

+| Tool | Version | Notes |
+|------|---------|-------|
+| JDK | 11 | Required. Not 8, not 17 |
+| Maven | 3.6.3+ | Use the wrapper `./mvnw` — no separate install needed |
+| Node.js | 18.x | Only for frontend (`zeppelin-web-angular/`) |
+


The prerequisites table uses || at the start of rows, which adds an empty column in GitHub Markdown rendering. Use a single leading | per row (or remove the leading pipe) to fix the table layout.

Copilot · 2026-04-04T05:49:30Z

AGENTS.md

+
+- **Java**: Google Java Style (2-space indent). Checkstyle enforced — no tabs, LF line endings, newline at EOF
+- **Frontend**: ESLint + Prettier, auto-enforced via pre-commit hook (Husky + lint-staged)
+- **Testing**: JUnit 4 + Mockito (Java), Playwright (frontend E2E)


The codebase primarily uses JUnit 5 (Jupiter) for Java tests (root pom.xml defines junit.jupiter.version and many tests import org.junit.jupiter.api.Test). This line saying “JUnit 4 + Mockito” is misleading; consider updating it to “JUnit 5 (Jupiter) + Mockito” (optionally noting that a small number of legacy JUnit 4 tests still exist).

Suggested change

- **Testing**: JUnit 4 + Mockito (Java), Playwright (frontend E2E)

- **Testing**: JUnit 5 (Jupiter) + Mockito (Java; a small number of legacy JUnit 4 tests still exist), Playwright (frontend E2E)

Copilot · 2026-04-04T05:49:31Z

AGENTS.md

+# Build only the module you're changing
+./mvnw clean package -pl zeppelin-server -DskipTests
+
+# Run tests for your module
+./mvnw test -pl zeppelin-server
+
+# Run a specific test
+./mvnw test -pl zeppelin-server -Dtest=NotebookServerTest#testMethod
+


These development workflow examples also omit --am. For module-only builds/tests (especially after clean), adding --am helps ensure required reactor dependencies are built (as shown in docs/development/contribution/useful_developer_tools.md).

jongyoul and others added 4 commits March 18, 2026 10:52

[ZEPPELIN-6405] Add AGENTS.md to RAT license check exclusion list

ea56e19

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

[ZEPPELIN-6405] Add Apache License header to AGENTS.md and revert RAT…

e7a8a3b

… exclusion Add the standard ASF license header to AGENTS.md instead of excluding it from the RAT license check. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

jongyoul marked this pull request as ready for review April 4, 2026 05:46

Copilot AI review requested due to automatic review settings April 4, 2026 05:46

Copilot started reviewing on behalf of jongyoul April 4, 2026 05:46 View session

Copilot AI reviewed Apr 4, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[ZEPPELIN-6405] Add AGENTS.md for AI coding agent guidance#5187

[ZEPPELIN-6405] Add AGENTS.md for AI coding agent guidance#5187
jongyoul wants to merge 4 commits intoapache:masterfrom
jongyoul:ZEPPELIN-6405-agents-md

jongyoul commented Mar 18, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 4, 2026

Uh oh!

Copilot AI Apr 4, 2026

Uh oh!

Copilot AI Apr 4, 2026

Uh oh!

Copilot AI Apr 4, 2026

Uh oh!

Copilot AI Apr 4, 2026

Uh oh!

Copilot AI Apr 4, 2026

Uh oh!

Copilot AI Apr 4, 2026

Uh oh!

Copilot AI Apr 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	- Testing: JUnit 4 + Mockito (Java), Playwright (frontend E2E)
	- Testing: JUnit 5 (Jupiter) + Mockito (Java; a small number of legacy JUnit 4 tests still exist), Playwright (frontend E2E)

Conversation

jongyoul commented Mar 18, 2026

Summary

Test plan

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 4, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 4, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 4, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 4, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 4, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 4, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 4, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 4, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants