This is an automated email from the ASF dual-hosted git repository. He-Pin pushed a commit to branch add-agents-and-clause-md in repository https://gitbox.apache.org/repos/asf/pekko-samples.git
commit 5114372cc642be45d4db4f156b76b0c4dbfee9d3 Author: 虎鸣 <[email protected]> AuthorDate: Mon Jun 15 00:20:02 2026 +0800 docs: add AGENTS.md and CLAUDE.md for AI coding agents Motivation: AI coding agents benefit from project-specific instructions to follow conventions, run correct validation, and produce consistent PRs. Modification: Add AGENTS.md with comprehensive rules (worktree, licensing, PR, formatting, validation, test, code, CI, commit format) and CLAUDE.md with a pre-PR verification checklist. Result: AI agents working on this repository will follow established conventions and produce higher-quality contributions. Tests: Not run - docs only References: None - AI agent configuration --- AGENTS.md | 151 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 17 +++++++ 2 files changed, 168 insertions(+) diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..18f9504 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,151 @@ +# Agent Rules for Apache Pekko Samples + +If this file conflicts with community conventions, 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. +- Follow the Licensing Rules below for every new file. + +## Project Structure + +- Each sample is a standalone sbt project in its own directory (e.g., `pekko-sample-cluster-java/`). +- Each sample has its own `build.sbt` and `README.md`. +- Samples come in Java and Scala variants where applicable. +- The `docs-gen/` directory generates documentation from samples. + +## Licensing Rules + +- Do not hand-write or invent license headers. Let sbt manage them. +- For new files, run `sbt headerCreateAll` to add the correct header. Do not manually paste header text. +- Existing files with copyright statements must keep those copyright statements intact. Never delete or rewrite an existing copyright notice; only add information. +- New files containing new code must use the standard Apache license header. + +## PR Rules + +- Every sample change must keep the sample compilable and runnable. +- Sample changes must update the corresponding `README.md`. +- Java and Scala variants of the same sample must stay in sync. +- Dependency changes must verify Apache-compatible licenses. +- Do not break the `docs-gen` build when changing samples referenced by documentation. + +## 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 +``` + +- Do not rely on IDE formatting alone. +- Do not commit unrelated formatting changes. + +## Validation Rules + +- Run the sample's tests. + +```shell +cd pekko-sample-name +sbt test +``` + +- Compile the sample to verify it remains valid. + +```shell +cd pekko-sample-name +sbt compile +``` + +- Run docs-gen to verify documentation generation. + +```shell +cd docs-gen +sbt run +``` + +- 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`. + +## Code Rules + +- Samples must be self-contained and easy to understand. +- Prefer clarity over cleverness in sample code. +- Each sample should demonstrate a specific Pekko feature or pattern. +- Keep Java and Scala variants functionally equivalent. +- Use `scala.jdk.*` converters for Java/Scala interop in Scala samples. + +## 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>`. +- Do not add `Co-authored-by` or AI-assistant trailers to commits or PR descriptions. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..e52a069 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,17 @@ +# Claude Rules for Apache Pekko Samples + +Follow `AGENTS.md`. + +Before opening or updating a PR, verify: + +- Changed samples compile and run successfully. +- Java and Scala variants of the same sample stay in sync. +- `README.md` is updated for any sample behavior changes. +- 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 to add headers for new files. Never hand-write or invent license headers; let sbt manage them, and preserve existing copyright notices intact. +- `docs-gen` still builds correctly if samples referenced by documentation were changed. +- Commit messages follow the `AGENTS.md` format. +- PR bodies follow the `AGENTS.md` format. +- `Tests` and `References` are present. +- No `Co-authored-by` or AI-assistant trailers are added to commits or PR descriptions. --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
