# Repository Guidelines

## Project Structure & Module Organization
- 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`.
- `apollo-biz` is a shared business-logic module used by services like config/admin (not a standalone service).
- Build and release tooling lives in `scripts/` (e.g., `scripts/build.sh`) and `apollo-buildtools/` (code style configs).
- Database and schema assets are under `scripts/sql` and module `src/main/resources` folders.
- Tests follow standard Maven layout: `*/src/test/java` and `*/src/test/resources` inside each module.
- Documentation is in `docs/`.

## Build, Test, and Development Commands
- `./mvnw -DskipTests package` builds all modules.
- `./mvnw test` runs the full test suite via Surefire (may log warnings if local meta/admin services are not running).
- `./mvnw -pl apollo-configservice -am test` runs tests for a specific module and its dependencies.
- `./mvnw spotless:apply` formats code and must be run before opening a PR.
- `./scripts/build.sh` generates distributable packages (used for deployment workflows).

## Coding Style & Naming Conventions
- Follow Google Java Style Guide; 2-space indentation and standard Java conventions apply.
- Use the IDE configs in `apollo-buildtools/style/` (IntelliJ/Eclipse).
- New Java classes should include a short Javadoc describing the class purpose.
- Use standard Java naming: packages `lower.case`, classes `UpperCamelCase`, tests `*Test`.

## OpenAPI Contract Workflow (apollo-portal)
- Treat OpenAPI as contract-first: update spec in `apolloconfig/apollo-openapi` before (or together with) portal implementation changes.
- `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`.
- 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.
- In PR review, verify contract alignment explicitly: endpoint path, request/response model, and permissions in `apollo` should match the spec in `apollo-openapi`.

## Testing Guidelines
- JUnit 5 is the default, with Vintage enabled for legacy JUnit 4 tests.
- Put new tests under the module’s `src/test/java` with `*Test` suffix.
- Add unit tests for new features or important bug fixes.

## Commit & Pull Request Guidelines
- Use Conventional Commits format (e.g., `feat:`, `fix:`).
- If a commit fixes an issue, append `Fixes #123` in the commit message.
- Commit only on feature branches; never commit directly to `master` or `main`.
- `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.
- Rebase onto `master` and squash feature work into a single commit before merge.
- 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.
- Non-trivial contributions require signing the CLA.
- Open a feature branch for your change and submit a PR using `.github/PULL_REQUEST_TEMPLATE.md`.
- PRs should include a clear description, tests run, and any relevant screenshots/logs; use GitHub issues for tracking.
- The PR checklist expects `mvn clean test`, `mvn spotless:apply`, and an update to `CHANGES.md`.
- For upstream contributions, open PRs against `apolloconfig/apollo` and fill the template with real content (not the raw template text).

## Security & Configuration Notes
- Apollo supports H2 in-memory for local development and MySQL for production; prefer H2 locally unless you need a real database.
- Review `scripts/sql` and environment config when using MySQL.
- Do not commit secrets or environment-specific credentials; use local overrides instead.
- Follow `SECURITY.md` for vulnerability reporting.