From 800260ef5c2bb8bef033cb99a1dd17287d2c81d5 Mon Sep 17 00:00:00 2001 From: harshitha-cstk Date: Fri, 17 Apr 2026 12:37:35 +0530 Subject: [PATCH] docs(DX-6048): add AGENTS.md, skills, and Cursor rules entry --- .cursor/rules/README.md | 5 +++ AGENTS.md | 43 ++++++++++++++++++++++++ skills/android/SKILL.md | 25 ++++++++++++++ skills/code-review/SKILL.md | 27 +++++++++++++++ skills/contentstack-android-cda/SKILL.md | 25 ++++++++++++++ skills/dev-workflow/SKILL.md | 26 ++++++++++++++ skills/framework/SKILL.md | 25 ++++++++++++++ skills/testing/SKILL.md | 29 ++++++++++++++++ 8 files changed, 205 insertions(+) create mode 100644 .cursor/rules/README.md create mode 100644 AGENTS.md create mode 100644 skills/android/SKILL.md create mode 100644 skills/code-review/SKILL.md create mode 100644 skills/contentstack-android-cda/SKILL.md create mode 100644 skills/dev-workflow/SKILL.md create mode 100644 skills/framework/SKILL.md create mode 100644 skills/testing/SKILL.md diff --git a/.cursor/rules/README.md b/.cursor/rules/README.md new file mode 100644 index 0000000..f5c1f87 --- /dev/null +++ b/.cursor/rules/README.md @@ -0,0 +1,5 @@ +# Cursor (optional) + +**Cursor** users: start at **[AGENTS.md](../../AGENTS.md)**. All conventions live in **`skills/*/SKILL.md`**. + +This folder only points contributors to **`AGENTS.md`** so editor-specific config does not duplicate the canonical docs. diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..0c98bd9 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,43 @@ +# Contentstack Android Delivery SDK – Agent guide + +**Universal entry point** for contributors and AI agents. Detailed conventions live in **`skills/*/SKILL.md`**. + +## What this repo is + +| Field | Detail | +|--------|--------| +| **Name:** | [contentstack-android](https://github.com/contentstack/contentstack-android) (`com.contentstack.sdk:android`) | +| **Purpose:** | Android library for the Contentstack Content Delivery API (Kotlin/Java consumers via AAR). | +| **Out of scope:** | Not the Java-only or iOS/Swift SDKs—those live in sibling repositories. | + +## Tech stack (at a glance) + +| Area | Details | +|------|---------| +| Language | Kotlin/Java; **compileSdk 34**; Java **17** compile options in `contentstack/build.gradle` | +| Build | Gradle (root `build.gradle`, `settings.gradle`, module **`contentstack/`**) | +| Tests | JUnit, Mockito, Robolectric, AndroidX Test—unit tests under `contentstack/src/test/` | +| Lint / coverage | JaCoCo integrated with debug unit tests (`testCoverageEnabled` on debug) | +| CI | `.github/workflows/check-branch.yml`, `publish-release.yml`, `sca-scan.yml`, `policy-scan.yml`, `codeql-analysis.yml` | + +## Commands (quick reference) + +| Command type | Command | +|--------------|---------| +| Unit tests (typical) | `./gradlew :contentstack:testDebugUnitTest` (from repo root) | +| Clean | `./gradlew clean` | + +## Where the documentation lives: skills + +| Skill | Path | What it covers | +|-------|------|----------------| +| **Development workflow** | [`skills/dev-workflow/SKILL.md`](skills/dev-workflow/SKILL.md) | Gradle, variants, CI, publishing | +| **Android CDA SDK** | [`skills/contentstack-android-cda/SKILL.md`](skills/contentstack-android-cda/SKILL.md) | Library API and module boundaries | +| **Android project layout** | [`skills/android/SKILL.md`](skills/android/SKILL.md) | `contentstack/` module, manifest, BuildConfig | +| **Testing** | [`skills/testing/SKILL.md`](skills/testing/SKILL.md) | Unit vs instrumented tests, Robolectric, JaCoCo | +| **Build & platform** | [`skills/framework/SKILL.md`](skills/framework/SKILL.md) | AGP, signing placeholders, `local.properties` | +| **Code review** | [`skills/code-review/SKILL.md`](skills/code-review/SKILL.md) | PR checklist | + +## Using Cursor (optional) + +If you use **Cursor**, [`.cursor/rules/README.md`](.cursor/rules/README.md) only points to **`AGENTS.md`**—same docs as everyone else. diff --git a/skills/android/SKILL.md b/skills/android/SKILL.md new file mode 100644 index 0000000..ccb954b --- /dev/null +++ b/skills/android/SKILL.md @@ -0,0 +1,25 @@ +--- +name: android +description: Use for Android module layout, Gradle config, and Kotlin/Java conventions in contentstack-android. +--- + +# Android project layout – contentstack-android + +## When to use + +- Editing `contentstack/build.gradle`, manifests, or source under `contentstack/src/` +- Adjusting `minSdk`, multidex, or packaging excludes + +## Instructions + +### Source trees + +- Follow standard Android library layout: **`main`**, **`test`**, **`androidTest`** under `contentstack/src/`. + +### Configuration + +- **`local.properties`** supplies machine-specific paths and optional keys—do not commit secrets; use the same keys the Gradle file expects (`host`, `APIKey`, etc. in `buildTypes`). + +### Java/Kotlin + +- Compile options target **Java 17** in the module—match language features accordingly. diff --git a/skills/code-review/SKILL.md b/skills/code-review/SKILL.md new file mode 100644 index 0000000..fb43584 --- /dev/null +++ b/skills/code-review/SKILL.md @@ -0,0 +1,27 @@ +--- +name: code-review +description: Use when reviewing PRs for contentstack-android—API stability, Gradle, tests, and mobile security. +--- + +# Code review – contentstack-android + +## When to use + +- Reviewing feature or fix PRs for the Android SDK +- Auditing dependency or manifest changes + +## Instructions + +### Checklist + +- **API**: Public SDK surface changes justified and documented. +- **Gradle**: Version bumps coherent; no accidental signing or secret commits. +- **Tests**: Unit tests for new logic; consider Robolectric limitations. +- **Manifest/resources**: No unnecessary permissions; ProGuard rules updated if needed. +- **Cross-SDK**: Behavior consistent with Java/Swift where applicable. + +### Severity hints + +- **Blocker**: Broken `:contentstack:testDebugUnitTest`, leaked credentials, or broken publish metadata. +- **Major**: Missing coverage for risky network or caching changes. +- **Minor**: Formatting, comments, internal refactors. diff --git a/skills/contentstack-android-cda/SKILL.md b/skills/contentstack-android-cda/SKILL.md new file mode 100644 index 0000000..1583fb2 --- /dev/null +++ b/skills/contentstack-android-cda/SKILL.md @@ -0,0 +1,25 @@ +--- +name: contentstack-android-cda +description: Use for the public Android Content Delivery SDK surface and package com.contentstack.sdk. +--- + +# Android CDA SDK – contentstack-android + +## When to use + +- Changing SDK entry points consumed by Android apps +- Working with stack configuration, entries, or HTTP client usage in this module + +## Instructions + +### Module + +- Primary code lives in **`contentstack/`** with namespace **`com.contentstack.sdk`** (`android { namespace ... }`). + +### API design + +- Keep public Java/Kotlin APIs stable for app developers—use semver for breaking changes in published AARs. + +### Integration + +- Behavior should stay aligned with other CDA SDKs where features overlap (queries, preview, etc.)—check parity with Java/Swift docs when adding features. diff --git a/skills/dev-workflow/SKILL.md b/skills/dev-workflow/SKILL.md new file mode 100644 index 0000000..ab06744 --- /dev/null +++ b/skills/dev-workflow/SKILL.md @@ -0,0 +1,26 @@ +--- +name: dev-workflow +description: Use for Gradle tasks, CI, release publishing, and branch flow in contentstack-android. +--- + +# Development workflow – contentstack-android + +## When to use + +- Running local builds/tests before a PR +- Aligning with GitHub Actions (branch checks, SCA, publish) + +## Instructions + +### Project shape + +- Root project **`contentstack-android`** includes module **`:contentstack`** (`settings.gradle`). + +### Commands + +- From repo root: `./gradlew :contentstack:testDebugUnitTest` for JVM unit tests on the library. +- Use `./gradlew clean` when switching branches or after AGP/cache issues. + +### CI + +- Workflows under `.github/workflows/` enforce policies and may publish artifacts—coordinate version bumps with `contentstack/build.gradle` `PUBLISH_*` fields. diff --git a/skills/framework/SKILL.md b/skills/framework/SKILL.md new file mode 100644 index 0000000..e176b47 --- /dev/null +++ b/skills/framework/SKILL.md @@ -0,0 +1,25 @@ +--- +name: framework +description: Use for AGP, Gradle plugins, JaCoCo, signing, and native Android build concerns in contentstack-android. +--- + +# Build & platform – contentstack-android + +## When to use + +- Upgrading Android Gradle Plugin, compile SDK, or dependencies +- Fixing signing, packaging excludes, or multidex issues + +## Instructions + +### Gradle + +- Root **`build.gradle`** pins AGP and Nexus publish plugin versions; module plugin **`com.android.library`** applies in `contentstack/build.gradle`. + +### Publishing + +- Maven coordinates use `PUBLISH_GROUP_ID`, `PUBLISH_ARTIFACT_ID`, `PUBLISH_VERSION`—bump with releases. + +### Keystore + +- Debug/release signing references **`key.keystore`** in the module—suitable for sample/debug only; production signing is consumer responsibility. diff --git a/skills/testing/SKILL.md b/skills/testing/SKILL.md new file mode 100644 index 0000000..759d280 --- /dev/null +++ b/skills/testing/SKILL.md @@ -0,0 +1,29 @@ +--- +name: testing +description: Use for JVM unit tests, Robolectric, AndroidX Test, and JaCoCo in contentstack-android. +--- + +# Testing – contentstack-android + +## When to use + +- Adding tests under `contentstack/src/test/` +- Debugging JaCoCo or unit-test-only failures + +## Instructions + +### Unit tests + +- Prefer **`testDebugUnitTest`** for fast feedback; Robolectric enables Android APIs on JVM where configured. + +### Instrumentation + +- **`androidTest`** exists for on-device tests—run on emulator/CI when changing UI-adjacent or integration paths. + +### Coverage + +- Debug builds enable **`testCoverageEnabled`**—JaCoCo outputs feed into reporting tasks defined in the module `build.gradle`. + +### Hygiene + +- Use **`MockWebserver`** and fixtures for HTTP; avoid embedding real stack credentials in the repo.