Skip to content

AGENTS.md

Latest commit

 

History

History
108 lines (86 loc) · 5.48 KB

AGENTS.md

File metadata and controls

108 lines (86 loc) · 5.48 KB
Raw

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.

Project overview

Sample code for the Maps SDK for Android. This is a multi-app repository:

Area Purpose
ApiDemos Feature demos in parallel java-app and kotlin-app variants plus common-ui
snippets Code excerpts published into the official documentation (app, app-ktx, app-utils, app-utils-ktx, app-compose, app-places-ktx)
tutorials Standalone mini-projects backing written tutorials, in java/ and kotlin/
FireMarkers Firebase + Maps sample app
WearOS Wear OS sample app

Region tags feed official documentation

Code excerpts in snippets/, as well as key sample activities in ApiDemos and root build files, are extracted into developers.google.com pages via region tag comment markers (paired START and END lines wrapping each excerpt).

  • Never rename, remove, or reorder region tags, and keep every START/END pair balanced.
  • Do not reformat or "clean up" code inside a tagged region unless the change is the point of the PR; the published docs mirror it verbatim.
  • Java and Kotlin snippet modules (app vs app-ktx) document the same features; a change to one usually needs the equivalent change in the other.

The same parity rule applies to ApiDemos: java-app and kotlin-app demonstrate the same features and must stay in sync.

Code style and hygiene

  • Adhere to formatting rules defined in .editorconfig.
  • Do not use wildcard imports (import foo.*); use explicit imports.
  • Avoid fully qualified class names in source code; declare explicit imports at the file level instead (except to resolve naming collisions or in XML layouts).
  • Target Java 17 (JavaLanguageVersion.of(17)) for all project modules. Do not downgrade bytecode to Java 8 or Java 11.

Building and testing

  • Full project verification:

    ./scripts/verify_all.sh                 # run assemble, unit tests, lint, and doc version checks across all root modules

  • Targeted module builds:

    ./gradlew :ApiDemos:kotlin-app:assembleDebug   # build a specific demo app
./gradlew :snippets:app-ktx:assembleDebug      # compile a specific snippet module

  • Documentation version check:

    python3 scripts/update_docs_versions.py --check # verify doc snippet versions match version catalog

  • ApiDemos smoke test (emulator, needs a real API key): opens every demo activity and checks that its map loads and that it survives a zoom and a configuration change. New demos are picked up from the manifest automatically.

    ./gradlew :ApiDemos:kotlin-app:connectedDebugAndroidTest \
  -Pandroid.testInstrumentationRunnerArguments.package=com.example.kotlindemos.smoke \
  -Pandroid.testInstrumentationRunnerArguments.requireMapLoaded=true

    For the Java app use :ApiDemos:java-app and com.example.mapdemo.smoke. Demos that need a map ID are skipped unless MAP_ID is set.

Snippet modules do not contain unit tests; they are verified through successful compilation (assembleDebug), Android lint (lintDebug), and doc version synchronization.

Running the apps requires a Maps API key: copy the keys named in local.defaults.properties (e.g. MAPS_API_KEY) into local.properties. The secrets-gradle-plugin injects them at build time. Never hardcode or commit API keys.

Note that most tutorials/ projects are standalone Gradle builds not wired into the root settings.gradle.kts; build them from their own directory.

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.

  • 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.

  • Several changes in one PR: a squash merge keeps only the PR title, so release-please would list one entry. When a PR contains several changes that belong in the changelog separately (for example several bug fixes), add a commit override block at the end of the PR description, one Conventional Commit per line. release-please uses these lines instead of the PR title:

    BEGIN_COMMIT_OVERRIDE
fix(ApiDemos): describe the first fix
fix(snippets): describe the second fix
END_COMMIT_OVERRIDE

    The PR title still has to be a valid Conventional Commit. Each line counts for the version bump, so a feat: or ! line bumps accordingly.

  • 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.

  • Keep changes scoped to one sample or one feature across its language variants; do not mix unrelated samples in one PR.

  • Build and test the affected modules before declaring work done, and report actual results.

  • 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).