From fc3245886d30dbe1f15568f3fb83cf058ca40703 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Enrique=20Lo=CC=81pez=20Man=CC=83as?= Date: Tue, 8 Sep 2026 15:37:02 +0700 Subject: [PATCH 1/2] docs: add AGENTS.md guidance for AI coding agents --- AGENTS.md | 65 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 1 + 2 files changed, 66 insertions(+) create mode 100644 AGENTS.md create mode 100644 CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..138fdea07 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,65 @@ +# AGENTS.md + +Guidance for AI coding agents working on this repository. For human contribution +rules (CLA, PR process, AI-assisted contribution policy), see [CONTRIBUTING.md](CONTRIBUTING.md). + +## Project overview + +The Maps SDK for Android Utility Library, split into focused submodules so +apps can depend only on what they need. `maps-utils` is the aggregator +artifact that pulls in all submodules; see [MIGRATION.md](MIGRATION.md) for +the 4.x to modular layout mapping. + +| Module | Purpose | +| --- | --- | +| `library` | Core utilities shared by the other modules | +| `clustering` | Marker clustering | +| `heatmaps` | Heatmap tile overlays | +| `data` | GeoJSON and KML parsing/rendering | +| `ui` | UI helpers (icon generators, bubbles) | +| `maps-utils` | Aggregator artifact, transitively includes the modules above | +| `lint-checks` | Custom Lint rules shipped with the library | +| `demo` | Demo app exercising the utilities | +| `visual-testing` | Screenshot/visual regression test harness | + +Shared Gradle conventions are in `build-logic/` (included build). + +## Building and testing + +```bash +./gradlew assembleDebug # build everything +./gradlew :clustering:testDebugUnitTest # unit tests for one module +./gradlew test # all unit tests +./gradlew lint # Android Lint (includes lint-checks rules) +``` + +Running the `demo` app requires a Maps API key in `secrets.properties` at the +repo root (see `local.defaults.properties` for the template). Never hardcode +or commit API keys. + +## Code style + +- Match the language and idiom of the file you are editing; new code is + Kotlin unless it extends an existing Java API surface. +- Formatting follows `.editorconfig`. +- KDoc/Javadoc on all public classes and methods; this is a widely consumed + library and its docs are published. +- Public API changes must be additive and backward compatible; deprecate + before removing. Breaking changes only in a major release with a + MIGRATION.md entry. +- Put a change in the most specific submodule, not `library`, unless it is + genuinely shared. + +## Pull requests + +- Use Conventional Commit messages (`feat:`, `fix:`, `docs:`, ...). + release-please parses them to generate versions and CHANGELOG.md; a wrong + prefix causes a wrong release bump. +- Never edit CHANGELOG.md or `.release-please-manifest.json` by hand. +- Every behavior change needs a unit test in the affected module. +- Run the module's tests and `lint` before declaring work done, and report + actual results. +- Do not add dependencies to library modules without discussion in an issue + first. +- AI tools must not be listed as authors or co-authors on commits or PRs, and + unsolicited bot-generated PRs are prohibited (see CONTRIBUTING.md). diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 000000000..43c994c2d --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md From b0246842d8f4e9f5874adeba93acbb24ec75a956 Mon Sep 17 00:00:00 2001 From: Dale Hawkins <107309+dkhawk@users.noreply.github.com> Date: Tue, 8 Sep 2026 14:37:05 -0600 Subject: [PATCH 2/2] docs: refine AGENTS.md with import hygiene, draft PR notification, and Java 17 target --- AGENTS.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 138fdea07..0d2e5c048 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -42,6 +42,9 @@ or commit API keys. - Match the language and idiom of the file you are editing; new code is Kotlin unless it extends an existing Java API surface. - Formatting follows `.editorconfig`. +- Do not use wildcard imports (`import foo.*`); use explicit imports. +- Avoid fully qualified class names in source code whenever possible; declare explicit imports at the file level instead (except to resolve naming collisions). +- Target **Java 17** (`JavaLanguageVersion.of(17)`) for all project modules. Do not downgrade bytecode to Java 8 or Java 11. - KDoc/Javadoc on all public classes and methods; this is a widely consumed library and its docs are published. - Public API changes must be additive and backward compatible; deprecate @@ -52,11 +55,13 @@ or commit API keys. ## Pull requests -- Use Conventional Commit messages (`feat:`, `fix:`, `docs:`, ...). +- Use Conventional Commit messages (`feat:`, `fix:`, `docs:`, `chore:`, `build(deps):`, `test:`, `refactor:`, `perf:`). release-please parses them to generate versions and CHANGELOG.md; a wrong prefix causes a wrong release bump. +- **PR Title Validation**: Ensure PR titles strictly conform to Conventional Commits (e.g., `fix: stale QuadItem removal` instead of `Fix stale QuadItem removal`). When PRs are squash-merged into `main`, GitHub uses the PR title as the default commit header; a non-conforming title prevents release-please from accurately categorizing changes in CHANGELOG.md or calculating semantic version increments. - Never edit CHANGELOG.md or `.release-please-manifest.json` by hand. - Every behavior change needs a unit test in the affected module. +- All pull requests are to be created as drafts (`gh pr create --draft`) until authorization is explicitly given to mark them ready for review. Always inform the user that the PR was created as a draft. - Run the module's tests and `lint` before declaring work done, and report actual results. - Do not add dependencies to library modules without discussion in an issue