From ecc743c0b803d70a0ab9493354be32ed02a2a18a Mon Sep 17 00:00:00 2001 From: Jason Song Date: Sun, 8 Feb 2026 11:51:40 +0800 Subject: [PATCH] docs: add AGENTS.md for contribution workflow --- AGENTS.md | 68 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 68 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..1041ba84 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,68 @@ +# Repository Guidelines + +## Project Structure & Module Organization +- Multi-module Maven repository with root `pom.xml`. +- Core modules: + - `apollo-core`: shared constants/utilities. + - `apollo-client`: main Java client and Spring integration. + - `apollo-client-config-data`: Spring Boot ConfigData integration. + - `apollo-mockserver`: test/mock support. + - `apollo-openapi`: OpenAPI client. + - `apollo-plugin`: plugin modules. +- Tests follow standard Maven layout: `*/src/test/java` and `*/src/test/resources`. +- CI workflows are in `.github/workflows`. + +## Build, Test, and Development Commands +- Build all modules: `mvn -B clean package -Dmaven.gitcommitid.skip=true` +- Run all tests: `mvn clean test` +- Run one module tests: `mvn -pl apollo-client clean test` +- Run targeted tests: `mvn -pl apollo-client -Dtest=ClassNameTest test` +- Compile only: `mvn -B clean compile -Dmaven.gitcommitid.skip=true` +- Notes: + - This repository does **not** configure `spotless`; do not use `spotless:apply` here. + - Some integration tests log connection warnings in local/dev environments; focus on final Maven summary. + +## Coding Style & Naming Conventions +- Java style: follow existing codebase conventions (Google-style Java patterns in current files). +- Keep changes minimal and module-scoped. +- Preserve existing package/class naming conventions. +- Add/adjust tests for non-trivial behavior changes. + +## Testing Guidelines +- JUnit 4 + JUnit Vintage are both used in this repo. +- For bug fixes: + - Add a regression test first when feasible. + - Run module-level tests for changed modules. + - Prefer full `mvn clean test` before opening PR. + +## Commit & Pull Request Guidelines +- Use Conventional Commits, e.g. `fix: ...`, `feat: ...`, `docs: ...`. +- If applicable, include issue linkage in commit message body, e.g. `Fixes #88`. +- Keep PR commits clean: + - Require a single commit in the PR branch before review (squash locally if needed). +- Open PRs with `.github/PULL_REQUEST_TEMPLATE.md` and fill all sections with concrete content. +- PR description should include: + - purpose/root cause + - change summary + - test commands actually run +- PR submission flow: + - Push branch to personal fork remote first (for example `origin`). + - Open PR from `:` to `apolloconfig/apollo-java:main`. + - If history is rewritten for squash, update remote branch with `--force-with-lease`. + +## CHANGES.md Rules +- Update `CHANGES.md` for user-visible fixes/features. +- Use bullet style consistent with existing entries. +- Entry format should be a Markdown link: + - link text = the actual change description + - link target = the PR URL (not issue URL) +- Example: + - `[Fix ... detailed summary](https://github.com/apolloconfig/apollo-java/pull/123)` + +## Agent Workflow Hints +- Reproduce first, then fix. +- Prefer targeted module/test runs during iteration, then run broader tests before PR. +- When creating upstream PRs: + - use a branch in personal fork + - base repository is `apolloconfig/apollo-java` + - ensure PR branch is squashed to one commit