AGENTS.md

1# Repository Guidelines
2 
3## Project Structure & Module Organization
4- Multi-module Maven repo with root `pom.xml` and service modules like `apollo-configservice`, `apollo-adminservice`, and `apollo-portal`, shared libs in `apollo-common`, and packaging in `apollo-assembly`.
5- `apollo-biz` is a shared business-logic module used by services like config/admin (not a standalone service).
6- Build and release tooling lives in `scripts/` (e.g., `scripts/build.sh`) and `apollo-buildtools/` (code style configs).
7- Database and schema assets are under `scripts/sql` and module `src/main/resources` folders.
8- Tests follow standard Maven layout: `*/src/test/java` and `*/src/test/resources` inside each module.
9- Documentation is in `docs/`.
10 
11## Build, Test, and Development Commands
12- `./mvnw -DskipTests package` builds all modules.
13- `./mvnw test` runs the full test suite via Surefire (may log warnings if local meta/admin services are not running).
14- `./mvnw -pl apollo-configservice -am test` runs tests for a specific module and its dependencies.
15- `./mvnw spotless:apply` formats code and must be run before opening a PR.
16- `./scripts/build.sh` generates distributable packages (used for deployment workflows).
17 
18## Coding Style & Naming Conventions
19- Follow Google Java Style Guide; 2-space indentation and standard Java conventions apply.
20- Use the IDE configs in `apollo-buildtools/style/` (IntelliJ/Eclipse).
21- New Java classes should include a short Javadoc describing the class purpose.
22- Use standard Java naming: packages `lower.case`, classes `UpperCamelCase`, tests `*Test`.
23 
24## OpenAPI Contract Workflow (apollo-portal)
25- Treat OpenAPI as contract-first: update spec in `apolloconfig/apollo-openapi` before (or together with) portal implementation changes.
26- `apollo-portal/pom.xml` uses `apollo.openapi.spec.url` + `openapi-generator-maven-plugin`; generated sources under `target/generated-sources/openapi/src/main/java` are added to compile path via `build-helper-maven-plugin`.
27- For new/changed OpenAPI endpoints, prefer implementing generated `*ManagementApi` interfaces and generated models; avoid introducing hand-written DTO/controller contracts that bypass the spec pipeline.
28- In PR review, verify contract alignment explicitly: endpoint path, request/response model, and permissions in `apollo` should match the spec in `apollo-openapi`.
29 
30## Testing Guidelines
31- JUnit 5 is the default, with Vintage enabled for legacy JUnit 4 tests.
32- Put new tests under the module’s `src/test/java` with `*Test` suffix.
33- Add unit tests for new features or important bug fixes.
34 
35## Commit & Pull Request Guidelines
36- Use Conventional Commits format (e.g., `feat:`, `fix:`).
37- If a commit fixes an issue, append `Fixes #123` in the commit message.
38- Commit only on feature branches; never commit directly to `master` or `main`.
39- `CHANGES.md` entries must use a PR URL in Markdown link format; if the PR URL is not available yet, open the PR first, then add/update `CHANGES.md` in a follow-up commit.
40- Rebase onto `master` and squash feature work into a single commit before merge.
41- When merging a PR on GitHub: if it has a single commit, use rebase and merge; if it has multiple commits, use squash and merge.
42- Non-trivial contributions require signing the CLA.
43- Open a feature branch for your change and submit a PR using `.github/PULL_REQUEST_TEMPLATE.md`.
44- PRs should include a clear description, tests run, and any relevant screenshots/logs; use GitHub issues for tracking.
45- The PR checklist expects `mvn clean test`, `mvn spotless:apply`, and an update to `CHANGES.md`.
46- For upstream contributions, open PRs against `apolloconfig/apollo` and fill the template with real content (not the raw template text).
47 
48## Security & Configuration Notes
49- Apollo supports H2 in-memory for local development and MySQL for production; prefer H2 locally unless you need a real database.
50- Review `scripts/sql` and environment config when using MySQL.
51- Do not commit secrets or environment-specific credentials; use local overrides instead.
52- Follow `SECURITY.md` for vulnerability reporting.
53