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-persistence-r2dbc.git
commit d9b6e6aadb234638a0fc492a07616bc736b4183d Author: 虎鸣 <[email protected]> AuthorDate: Mon Jun 15 00:19:54 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 | 231 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 20 ++++++ 2 files changed, 251 insertions(+) diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..b6292bd --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,231 @@ +# Agent Rules for Apache Pekko Persistence R2DBC + +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. +- Follow the Licensing Rules below for every new file. + +## 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. +- Run `sbt +headerCheckAll` to verify all files carry the expected header. +- 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. Do not add the special Pekko header that mentions Akka unless you are copying code from an existing Akka-derived file. +- If you copy code from another file in this repository, preserve that file's original headers in the new file. +- If you copy code from an external project, do not commit it silently. Note the source in the PR description so maintainers can verify license compatibility and update `LICENSE` if needed. +- `sbt headerCreateAll` does not know the origin of new code; you must still record copied-code provenance in the PR. + +## 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. +- Database schema changes must include migration scripts and backward compatibility considerations. +- Changes must be tested against at least one supported database (PostgreSQL, YugabyteDB). + +## Package Requirements + +### Coursier + +Install Coursier (`cs` command). + +On x86-64 (aka AMD64) +``` +curl -fL "https://github.com/coursier/launchers/raw/master/cs-x86_64-pc-linux.gz"; | gzip -d > cs +``` +On ARM64 +``` +curl -fL "https://github.com/VirtusLab/coursier-m1/releases/latest/download/cs-aarch64-pc-linux.gz"; | gzip -d > cs +``` + +### sbt + +``` +cs setup +``` + +### scalafmt + +``` +cs install scalafmt +``` + +## 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 "core / Test / testOnly fully.qualified.SpecName" +``` + +- Run migration tests. + +```shell +sbt "migration / test" +``` + +- 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. +- ALL reported MiMa issues must be fixed before creating or updating a PR. Do not ignore or suppress MiMa warnings without explicit maintainer approval. +- 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. +- R2DBC integration tests require a running PostgreSQL or YugabyteDB instance. If unavailable, record in `Tests`. + +## 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. +- SQL queries must be parameterized to prevent injection. Never concatenate user input into SQL strings. +- Serialization changes must consider rolling upgrade compatibility for existing persistent events. +- Reactive streams backpressure must be respected in all database operations. + +## 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>`. +- 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..acc2f00 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,20 @@ +# Claude Rules for Apache Pekko Persistence R2DBC + +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 to add headers for new files. Never hand-write or invent license headers; let sbt manage them, and preserve existing copyright notices intact. +- For copied code, the source file or external project is noted in the PR (see Licensing Rules in `AGENTS.md`). +- Binary compatibility is preserved, and the GitHub `Check / Binary Compatibility` job passes before merge. +- `sbt +mimaReportBinaryIssues` was run for public API, binary shape, or MiMa-sensitive internal changes, and ALL reported issues were fixed before creating or updating the PR. +- Database schema changes include migration scripts. +- Changes are tested against at least one supported database (PostgreSQL, YugabyteDB). +- Migration module changes preserve data integrity. +- 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]
