|
| 1 | +# Repository Guidelines |
| 2 | + |
| 3 | +## Project Structure & Modules |
| 4 | +- Root is a Maven multi-module project using the Maven Wrapper (`mvnw`). |
| 5 | +- Modules: `core` (library), `cli` (fat-jar CLI), `maven` (Maven plugin), `maven-example` (plugin usage example). |
| 6 | +- Tests live under `<module>/src/test/java`, with fixtures in `<module>/src/test/resources` (e.g., `core/src/test/resources`). |
| 7 | + |
| 8 | +## Build, Test, and Run |
| 9 | +- Build all modules: `./mvnw clean package` |
| 10 | +- Run tests only: `./mvnw test` |
| 11 | +- Format code: `./mvnw fmt:format` (runs pre-commit via githook as well) |
| 12 | +- CLI jar (shaded): `cli/target/openapi-diff-cli-<version>-all.jar` |
| 13 | + - Example run: `java -jar cli/target/openapi-diff-cli-2.2.0-SNAPSHOT-all.jar old.yaml new.yaml --markdown diff.md` |
| 14 | +- Docker (optional): `docker build -t local-openapi-diff .` then run as shown in README. |
| 15 | + |
| 16 | +## Coding Style & Naming |
| 17 | +- Language: Java 8 (`maven.compiler.source/target=1.8`). |
| 18 | +- Formatter: Google Java Format via `fmt-maven-plugin` (use `./mvnw fmt:format`; do not hand-wrap). |
| 19 | +- Packages: `org.openapitools.openapidiff...` |
| 20 | +- Tests: JUnit 5; name classes `*Test.java` and use clear method names (Given_When_Then optional). |
| 21 | + |
| 22 | +## Testing Guidelines |
| 23 | +- Framework: JUnit Jupiter (5.x); assertions via AssertJ. |
| 24 | +- Run module tests: `./mvnw -pl <module> -am test` |
| 25 | +- Coverage: JaCoCo agent is configured; keep or improve coverage around changed code. |
| 26 | +- Add minimal, focused tests near the change (unit in `core`, integration/usage in `cli` or `maven`). |
| 27 | + |
| 28 | +## Commit & Pull Request Guidelines |
| 29 | +- Style: Conventional Commits (e.g., `feat(core): add schema diff`, `fix(cli): handle empty URLs`, `build(deps): bump junit-bom`). |
| 30 | +- Message: imperative, concise subject (<72 chars), details in body; reference issues (e.g., `Fixes #123`). |
| 31 | +- PRs: include a clear summary, scope/module, reasoning, and before/after behavior; link issues; include CLI examples or output snippets when relevant. |
| 32 | +- CI must pass; run `./mvnw fmt:format test package` locally before opening PR. |
| 33 | + |
| 34 | +## Security & Configuration |
| 35 | +- Prefer local files for specs during tests; avoid fetching remote URLs in unit tests. |
| 36 | +- CLI supports `--config-file` and `--config-prop` to override defaults; include sample configs in tests when adding new checks. |
0 commit comments