This is an automated email from the ASF dual-hosted git repository.
wenjin272 pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/flink-agents.git
The following commit(s) were added to refs/heads/main by this push:
new 7c8d200b [infra] Add AGENTS.md (#878)
7c8d200b is described below
commit 7c8d200b07c50cf82efb4ed579c8d47d979181ca
Author: Wenjin Xie <[email protected]>
AuthorDate: Wed Jul 8 10:14:34 2026 +0800
[infra] Add AGENTS.md (#878)
---
AGENTS.md | 30 +++++++++++
code_review.md | 148 ++++++++++++++++++++++++++++++++++++++++++++++++++++
tools/.rat-excludes | 4 +-
3 files changed, 181 insertions(+), 1 deletion(-)
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 00000000..43d1601a
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,30 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+
+Flink Agents is a mixed Java and Python project with aligned module concepts
across both languages. The core modules are `api/`, `plan/`, and `runtime/`;
preserve the `runtime -> plan -> api` dependency direction in both Java and
Python, with no reverse dependencies. `integrations/` contains ecosystem
integrations. `e2e-test/` and `python/flink_agents/e2e_tests/` contain
end-to-end tests, including cross-language suites. Java code follows
`src/main/java` and `src/test/java`; Python code [...]
+
+## Build, Test, and Development Commands
+
+Use repository scripts as entry points, and read the script source or help
output before choosing flags, Flink versions, or environment variables.
+
+- `./tools/build.sh`: builds Java artifacts, distribution JARs, Python
dependencies, and the wheel.
+- `./tools/ut.sh`: runs Java, Python, and end-to-end test suites.
+- `./tools/lint.sh`: formats or checks Python with Ruff and Java with Spotless.
+- `./tools/check-license.sh`: verifies or fixes Apache license headers.
+
+## Coding Style & Naming Conventions
+
+Java targets Java 11 and is formatted by Spotless using google-java-format
AOSP style. Use package paths under `org.apache.flink.agents.*`,
`UpperCamelCase` classes, and test classes ending in `Test`. Python requires
3.10 through 3.12, uses Ruff with an 88-character line length, Google-style
docstrings, absolute imports, and `snake_case` for modules, functions, and test
files. Public API changes must keep Java, Python, and YAML APIs semantically
aligned.
+
+## Testing Guidelines
+
+Java tests use JUnit 5 with AssertJ and Mockito. Python tests use pytest;
integration tests are marked with `integration` and can require external
services such as Ollama, OpenAI, Chroma, or mem0. Before Python-facing tests,
including cross-language suites, export `PYTHONPATH=$(python3 -c 'import
sysconfig; print(sysconfig.get_paths()["purelib"])')` or the equivalent path
from the active Python environment. Prefer focused tests near the changed
module, then run `./tools/ut.sh` or the rel [...]
+
+## Commit & Pull Request Guidelines
+
+Use concise subjects with bracketed components, matching existing history,
such as `[python] Admit bytes in memory values` or `[api][java] Add event
constants`. For nontrivial behavior changes, open or link a GitHub issue before
the PR. PR titles should include relevant components like `[api]`, `[runtime]`,
`[java]`, `[python]`, or `[hotfix]`; describe the change, test evidence, and
any compatibility impact.
+
+## Code Review
+
+Before reviewing a PR, read `code_review.md`. For GitHub PRs, read existing
unresolved human review threads and include relevant already-raised issues in
the local review conclusion, marked as human-raised. Apply its passes for
runtime call paths, Java/Python parity, cross-language bridges, root-cause
removal, and targeted verification.
diff --git a/code_review.md b/code_review.md
new file mode 100644
index 00000000..9f33b3ff
--- /dev/null
+++ b/code_review.md
@@ -0,0 +1,148 @@
+# Code Review Guide
+
+This guide records repository-specific expectations for pull request reviews.
+It is meant to be read before reviewing a PR.
+
+## Review Posture
+
+Prioritize correctness, runtime behavior, API design, compatibility policy,
+regression risk, and missing tests. Findings should be concrete and tied to
+files, lines, and call paths.
+
+Flink Agents is beta. Breaking changes are acceptable when they remove unsafe
+design, clarify contracts, or prevent old bug paths from remaining available.
+Do not keep an API, fallback, or mutable state channel only for compatibility
+when it conflicts with the new design.
+
+## Required Review Passes
+
+1. Understand the issue or feature goal.
+2. For GitHub PRs, read existing unresolved human review threads before
+ finalizing findings.
+3. Read the diff, then trace the full runtime call path outside the diff.
+4. Search all call sites of changed public, protected, and cross-language APIs.
+5. Decide whether changed APIs should be kept, documented, deprecated, or
+ deleted.
+6. Check user-facing names, docs, and error messages for implementation leaks,
+ stale comments, or ambiguous contracts.
+7. Check whether the root cause channel still exists through old APIs,
+ defaults, fallback behavior, or mutable shared state.
+8. Compare equivalent Java, Python, and YAML-facing behavior.
+9. Check cross-language wrappers, adapters, serializers, and runtime bridge
+ code when the change crosses Java/Python boundaries.
+10. Check dependency, license, NOTICE, and shared-fixture changes when new
+ libraries or generated/bundled artifacts are introduced.
+11. Verify tests cover the behavior at the level where the bug happened.
+12. Run targeted tests or clearly state why they could not be run.
+13. Separate findings into blockers, non-blocking risks, and test gaps. Include
+ relevant human-raised issues in the conclusion, marked as already raised by
+ a human reviewer.
+
+## Root-Cause Checklist
+
+For bugfix PRs, ask:
+
+- What exact state, call ordering, or contract caused the bug?
+- Does the PR remove that cause, or only avoid reading it in one code path?
+- After the fix, can any remaining entry point, overload, default value, or
+ fallback still reach the old unsafe behavior?
+- If the PR adds or changes a configuration option, is the documented behavior
+ honored everywhere that option can affect runtime behavior, including default
+ values and code that runs before the main action or evaluator?
+- Are tests exercising the original failure mode, not just a lower-level
helper?
+
+## API And Documentation Clarity
+
+For public APIs, configuration, and common runtime extension points, ask:
+
+- Do names and error messages describe user-facing behavior instead of exposing
+ implementation details?
+- Does a doc comment describe the final contract, not old implementation
+ history, generated rationale, or a not-yet-existing parallel implementation?
+- Do changed user inputs reject values that were previously valid? If so, is
the
+ incompatibility intentional, documented, and covered by tests?
+- Are invalid user inputs rejected with clear errors that name the invalid
value
+ and the expected format or contract?
+- Are internal terms kept inside implementation classes unless callers need
+ those concepts to use the API correctly?
+
+## Beta Breaking-Change Policy
+
+Because the project is beta, reviewers should actively recommend deleting
+unsafe or misleading APIs when doing so simplifies the contract.
+
+When reviewing a public API change:
+
+- search internal production call sites and tests separately
+- identify external compatibility risk, but do not assume it blocks the change
+- prefer one safe contract over two partially compatible contracts
+- avoid keeping convenience overloads that encourage the old unsafe behavior
+- ask whether tests should move from old APIs to the new intended API
+
+## Java, Python, And YAML Parity
+
+For equivalent Java/Python APIs and YAML-facing resource declarations, compare:
+
+- null and `None` semantics
+- default arguments
+- no-op behavior
+- exception behavior
+- metric path and group naming
+- sync, async, retry, and recovery paths
+- tool-call and follow-up request paths
+- resource names, YAML aliases/specs, and examples
+
+Do not accept semantically different contracts unless the difference is
+intentional and documented.
+
+## Test Expectations
+
+Tests should match the risk and blast radius.
+
+For any behavior change:
+
+- when a config option changes runtime behavior, test it through the production
+ config path, including the default behavior
+- add an end-to-end or near end-to-end test when a runtime routing or operator
+ behavior changes
+
+For bugfixes:
+
+- add a regression test that fails on the old behavior when practical
+- test the actual action/runtime path where the bug appeared
+- avoid relying only on helper-method tests
+- cover both Java and Python paths when the feature exists in both
+- include async, retry, delayed callback, tool-call, or recovery paths when
+ they affect the behavior
+
+For API cleanup:
+
+- update tests to use the intended API
+- remove tests that only preserve deleted compatibility paths
+- add contract tests for null/`None` or default behavior when relevant
+
+## Dependencies And Shared Fixtures
+
+When a PR adds libraries or shared test data, ask:
+
+- Are LICENSE and NOTICE updated for bundled or shaded dependencies, including
+ transitives?
+- If a module is added to `dist` or a dependency is bundled/shaded, does the
+ dist dependency tree match NOTICE and bundled license files?
+- When adding a public integration or resource, are module registration, dist
+ registration, resource names, YAML aliases, docs/examples, and wrappers
+ updated or intentionally omitted?
+- Are shared test fixtures placed where every consuming module can depend on
+ them without violating module boundaries?
+
+## Verification
+
+Before claiming a review is complete, run focused verification commands when
+possible. Report the exact commands and outcomes.
+
+If local workspace changes unrelated to the PR block tests, do not edit or
+revert them just to force a run. Either use a clean export/worktree or report
+the blocker clearly.
+
+If a command fails because of local environment restrictions, identify whether
+the failure is from the PR, the workspace, missing dependencies, or sandboxing.
diff --git a/tools/.rat-excludes b/tools/.rat-excludes
index 11e47ca7..e58064b5 100644
--- a/tools/.rat-excludes
+++ b/tools/.rat-excludes
@@ -22,4 +22,6 @@ PULL_REQUEST_TEMPLATE.md
.*\.egg-info/*
licenses/*
skills/*
-.*\.yaml$
\ No newline at end of file
+.*\.yaml$
+AGENTS.md
+code_review.md
\ No newline at end of file
