Skip to content

AGENTS.md

Latest commit

 

History

History
59 lines (45 loc) · 4.32 KB

AGENTS.md

File metadata and controls

59 lines (45 loc) · 4.32 KB
Raw

Agent Guide

Read this file first. It tells you where to find context in this repo.

Quick Reference

What you need Where to look
How this repo is structured ARCHITECTURE.md
How to build/test/run CONTRIBUTING.md
Why decisions were made docs/ADRs/
What this repo does README.md
PR review rules .bito/guidelines/
Active specs/work docs/specs/

Sharp Edges & Invariants

  • Never call environment-scoped operations on the wrong modules. The modules apiKeys, previewApiKeys, roles, spaceMemberships, uploads, and webhooks throw CMANotWithEnvironmentsException if the client is configured with a non-master environmentId. Always use a separate client (no environmentId) for those modules.
  • Java 8 is the minimum target — do not use Java 9+ APIs in production code. The Android dependency (com.google.android:android) is marked optional but must remain compilable on API 21+. Tests may use newer JVM features.
  • Do not add new runtime dependencies without an ADR. The dependency footprint is deliberately small to keep Android app size predictable.
  • Every Module must extend AbsModule<T>. The base class handles argument validation, executor injection, and space/environment ID pre-configuration. Never bypass it.
  • Custom Gson adapters must be registered in CMAClient. The Gson instance is built once in CMAClient and shared across all modules. New model types with non-trivial wire formats need a type adapter registered there.
  • RichText hierarchy rules are enforced by the API — the SDK models them but does not validate at write time. Violating the hierarchy (Document in Document, Link outside Paragraph, etc.) will produce a 422 from the CMA. See ARCHITECTURE.md for the full rule set.
  • The CMACallback.onFailure() default implementation is empty. Code that needs to handle failures must override it explicitly. This is a common source of silently dropped errors.
  • Test files are Kotlin; production code is Java. Keep this split. Do not introduce Kotlin into src/main/java/.
  • Public API surface is stable — treat changes as breaking. All CMA* model classes, CMAClient builder methods, and Module* public methods are part of the published API. Removing, renaming, or adding required parameters to any of these is a breaking change and requires a semver major bump. Review CHANGELOG implications before modifying them.
  • Never log auth tokens unconditionally. The logSensitiveData flag in CMAClient controls whether Authorization headers appear in logs. Its default is false. Do not change that default or add unconditional logging of auth/credentials anywhere in the SDK.
  • Checkstyle runs during ./mvnw verify (not ./mvnw test). CI only runs ./mvnw -B test, so checkstyle is not enforced in CI — run ./mvnw -B verify locally before pushing to catch violations. The config is in checkstyle.xml at the repo root.

Key Conventions

  • Commit format: Conventional Commits (feat:, fix:, chore:, docs:, etc.) — not enforced by a hook, but followed by convention
  • Branch strategy: master is the main branch; feature/fix branches merged via PR; releases use release/X.Y.Z branches
  • Test location: src/test/kotlin/com/contentful/java/cma/ (unit) and src/test/kotlin/com/contentful/java/cma/e2e/ (integration)
  • Build system: Maven Wrapper (./mvnw) — always use the wrapper, never a system Maven install
  • Module pattern: One Module*.java + one Service*.java per CMA resource type
  • Model naming: All resource model classes are prefixed CMA (e.g., CMAEntry, CMASpace)

Integration Points

Upstream (this repo consumes):

  • Contentful CMA (api.contentful.com) — all content management operations
  • Contentful Upload API (upload.contentful.com) — binary asset upload

Downstream (consumes this repo):

  • Java and Android applications that manage Contentful content
  • Published to Maven Central as com.contentful.java:cma-sdk

Build & Quality

# Run tests (does NOT include checkstyle)
./mvnw -B test

# Full verification (tests + checkstyle) inside devcontainer
./mvnw -B verify