This is an automated email from the ASF dual-hosted git repository.
He-Pin pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/pekko.git
The following commit(s) were added to refs/heads/main by this push:
new dd2533b78a Add AI agent contribution rules (#2911)
dd2533b78a is described below
commit dd2533b78af966a786bd35276880c6626a6aead6
Author: He-Pin(kerr) <[email protected]>
AuthorDate: Tue Apr 28 13:15:27 2026 +0800
Add AI agent contribution rules (#2911)
Motivation:
AI assistants need concise repository-specific rules that reflect the Pekko
contribution workflow before PRs.
Modification:
Add AGENTS.md with rules for scoped patches, directional tests, native
scalafmt, javafmt/header tasks, validation, code conventions, and commit/PR
body format. Add CLAUDE.md as the Claude entrypoint that delegates to AGENTS.md.
Result:
Future AI changes have a shared checklist that emphasizes directional
tests, native scalafmt, sbt javafmtAll, sbt headerCreateAll, Tests, and
References.
Tests:
- git diff --check
- scalafmt --list --mode diff-ref=origin/main
- JDK17 sbt javafmtAll
- sbt headerCreateAll
- Not run - code tests; docs-only agent guidance.
References:
None - docs-only agent guidance.
---
AGENTS.md | 184 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
CLAUDE.md | 15 +++++
2 files changed, 199 insertions(+)
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000000..583613c743
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,184 @@
+# Agent Rules for Apache Pekko
+
+Follow `CONTRIBUTING.md`. If this file conflicts with `CONTRIBUTING.md`,
follow `CONTRIBUTING.md` and update this file.
+
+## Worktree Rules
+
+- Base new work on `origin/main` unless the user or maintainer requests
another branch.
+- Keep every PR scoped to one change.
+- Do not mix behavior changes, formatting churn, dependency updates, and
unrelated cleanup.
+- Do not revert user changes or unrelated local changes.
+- Use `rg` or `rg --files` for repository searches.
+- Read neighboring code before editing.
+- Preserve existing license and copyright notices.
+- Do not add `@author` tags.
+
+## PR Rules
+
+- Every non-doc-only PR must add or update a directional test.
+- Directional test: focused behavior or regression test with explicit
assertions.
+- Bug-fix tests must fail or expose the issue before the fix.
+- CI-flake tests must encode the intended ordering, scheduling, timeout, or
concurrency contract.
+- Documentation-only PRs must use `Tests: Not run - docs only`.
+- Behavior, configuration, public API, or operator changes must update docs.
+- Scala and Java DSL changes must keep API, docs, and tests in parity.
+- Public API, binary shape, serialization, or MiMa-sensitive internal changes
must preserve binary compatibility.
+- The GitHub `Check / Binary Compatibility` job must pass before merge.
+- Wire protocol changes must consider rolling upgrade compatibility.
+- Dependency changes must verify Apache-compatible licenses.
+
+## Formatting Rules
+
+- Prefer native scalafmt for changed Scala and SBT files when it is available.
+
+```shell
+git fetch origin main
+scalafmt --mode diff-ref=origin/main
+scalafmt --list --mode diff-ref=origin/main
+```
+
+- If native scalafmt is not installed, use the sbt scalafmt tasks or record
that scalafmt could not be run.
+
+```shell
+sbt scalafmtAll scalafmtSbt
+sbt scalafmtCheckAll scalafmtSbtCheck
+```
+
+- Use JDK 17 for Java formatter tasks.
+
+```shell
+export JAVA_HOME=$(/usr/libexec/java_home -v 17)
+export PATH="$JAVA_HOME/bin:$PATH"
+sbt javafmtAll
+```
+
+- Run header generation before PR.
+
+```shell
+sbt headerCreateAll
+```
+
+- Run checks when relevant.
+
+```shell
+sbt javafmtCheckAll
+sbt +headerCheckAll
+sbt checkCodeStyle
+```
+
+- Use `sbt sortImports` when imports change.
+- Do not rely on IDE formatting alone.
+- Do not commit unrelated formatting changes.
+
+## Validation Rules
+
+- Run the smallest focused test first.
+
+```shell
+sbt "module-name / Test / testOnly fully.qualified.SpecName"
+```
+
+- Use JDK-specific configs when relevant.
+
+```shell
+sbt "module-name / TestJdk9 / testOnly fully.qualified.SpecName"
+```
+
+- Run PR impact validation for non-trivial code changes.
+
+```shell
+sbt validatePullRequest
+```
+
+- Set `PR_TARGET_BRANCH` only when the PR target is not `main`.
+
+```shell
+PR_TARGET_BRANCH=origin/example sbt validatePullRequest
+```
+
+- Run MiMa for public API, binary shape, serialization, or MiMa-sensitive
internal changes.
+
+```shell
+sbt +mimaReportBinaryIssues
+```
+
+- Do not mark a PR ready while the local MiMa run or the GitHub `Check /
Binary Compatibility` job is failing.
+- Run Paradox for documentation changes that touch project docs.
+
+```shell
+sbt docs/paradox
+```
+
+- Always run `git diff --check`.
+- Do not assume local tools such as `sbt` or `scalafmt` are installed; if a
required tool is missing, record the missing tool and skipped command in
`Tests`.
+- Skipped or environment-failed commands must be recorded in `Tests`.
+
+## Test Rules
+
+- Prefer deterministic tests over larger timeouts.
+- Avoid `Thread.sleep`.
+- Prefer probes, latches, stepped components, `within`, `remaining`, and
`remainingOrDefault`.
+- Keep `expectNoMessage` short and intentional.
+- Do not weaken assertions to hide production behavior.
+- Do not fix flakes only by increasing timeouts.
+
+## Code Rules
+
+- Match existing module patterns.
+- Prefer local helpers and established abstractions.
+- Put non-public shared implementation in `internal` packages where
appropriate.
+- Mark Java-visible internals with `private[pekko]`, `@InternalApi`, and
`INTERNAL API` Scaladoc.
+- For public Java APIs, avoid Scala default parameters, lower type bounds,
deeply nested traits, and Scala-only collection types.
+- Use `scala.jdk.*` converters for Java/Scala interop.
+- For new Pekko Streams operators, update operator docs and consistency
coverage.
+
+## CI and JDK Rules
+
+- Read exact GitHub Actions logs before changing code for CI failures.
+- Reproduce JDK-specific failures on the same JDK when possible.
+- For JDK 21+ nightly virtual-thread behavior, read the matching section in
`CONTRIBUTING.md`.
+- Do not treat a pass on a different JDK as proof for a JDK-specific failure.
+
+## Commit and PR Format
+
+- Use this body format for non-trivial commits.
+
+```text
+Motivation:
+Problem or requirement.
+
+Modification:
+Change summary.
+
+Result:
+New outcome.
+
+Tests:
+- command/result or Not run - docs only
+
+References:
+Fixes #1234, Refs #1234, or None - <short context>
+```
+
+- Use this PR body format.
+
+```markdown
+### Motivation
+Problem or requirement.
+
+### Modification
+Change summary.
+
+### Result
+New outcome.
+
+### Tests
+- command/result or Not run - docs only
+
+### References
+Fixes #1234, Refs #1234, or None - <short context>
+```
+
+- Never omit `Tests`.
+- Never omit `References`.
+- Use `Refs #...`, `Fixes #...`, or `None - <short context>`.
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000000..bc4b357d31
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,15 @@
+# Claude Rules for Apache Pekko
+
+Follow `AGENTS.md`.
+
+Before opening or updating a PR, verify:
+
+- Non-doc-only changes have directional tests.
+- Native `scalafmt` or the sbt scalafmt tasks were run for changed Scala/SBT
files, or the missing tool is recorded in `Tests`.
+- `sbt javafmtAll` was run with JDK 17 when relevant.
+- `sbt headerCreateAll` was run.
+- Binary compatibility is preserved, and the GitHub `Check / Binary
Compatibility` job passes before merge.
+- `sbt +mimaReportBinaryIssues` was run for public API, binary shape,
serialization, or MiMa-sensitive internal changes.
+- Commit messages follow the `AGENTS.md` format.
+- PR bodies follow the `AGENTS.md` format.
+- `Tests` and `References` are present.
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
