Skip to content

Commit 800260e

Browse files
harshitha-cstkharshitha-cstk
committed
docs(DX-6048): add AGENTS.md, skills, and Cursor rules entry
1 parent 99cf945 commit 800260e

8 files changed

Lines changed: 205 additions & 0 deletions

File tree

‎.cursor/rules/README.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Cursor (optional)
2+
3+
**Cursor** users: start at **[AGENTS.md](../../AGENTS.md)**. All conventions live in **`skills/*/SKILL.md`**.
4+
5+
This folder only points contributors to **`AGENTS.md`** so editor-specific config does not duplicate the canonical docs.

‎AGENTS.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# Contentstack Android Delivery SDK – Agent guide
2+
3+
**Universal entry point** for contributors and AI agents. Detailed conventions live in **`skills/*/SKILL.md`**.
4+
5+
## What this repo is
6+
7+
| Field | Detail |
8+
|--------|--------|
9+
| **Name:** | [contentstack-android](https://github.com/contentstack/contentstack-android) (`com.contentstack.sdk:android`) |
10+
| **Purpose:** | Android library for the Contentstack Content Delivery API (Kotlin/Java consumers via AAR). |
11+
| **Out of scope:** | Not the Java-only or iOS/Swift SDKs—those live in sibling repositories. |
12+
13+
## Tech stack (at a glance)
14+
15+
| Area | Details |
16+
|------|---------|
17+
| Language | Kotlin/Java; **compileSdk 34**; Java **17** compile options in `contentstack/build.gradle` |
18+
| Build | Gradle (root `build.gradle`, `settings.gradle`, module **`contentstack/`**) |
19+
| Tests | JUnit, Mockito, Robolectric, AndroidX Test—unit tests under `contentstack/src/test/` |
20+
| Lint / coverage | JaCoCo integrated with debug unit tests (`testCoverageEnabled` on debug) |
21+
| CI | `.github/workflows/check-branch.yml`, `publish-release.yml`, `sca-scan.yml`, `policy-scan.yml`, `codeql-analysis.yml` |
22+
23+
## Commands (quick reference)
24+
25+
| Command type | Command |
26+
|--------------|---------|
27+
| Unit tests (typical) | `./gradlew :contentstack:testDebugUnitTest` (from repo root) |
28+
| Clean | `./gradlew clean` |
29+
30+
## Where the documentation lives: skills
31+
32+
| Skill | Path | What it covers |
33+
|-------|------|----------------|
34+
| **Development workflow** | [`skills/dev-workflow/SKILL.md`](skills/dev-workflow/SKILL.md) | Gradle, variants, CI, publishing |
35+
| **Android CDA SDK** | [`skills/contentstack-android-cda/SKILL.md`](skills/contentstack-android-cda/SKILL.md) | Library API and module boundaries |
36+
| **Android project layout** | [`skills/android/SKILL.md`](skills/android/SKILL.md) | `contentstack/` module, manifest, BuildConfig |
37+
| **Testing** | [`skills/testing/SKILL.md`](skills/testing/SKILL.md) | Unit vs instrumented tests, Robolectric, JaCoCo |
38+
| **Build & platform** | [`skills/framework/SKILL.md`](skills/framework/SKILL.md) | AGP, signing placeholders, `local.properties` |
39+
| **Code review** | [`skills/code-review/SKILL.md`](skills/code-review/SKILL.md) | PR checklist |
40+
41+
## Using Cursor (optional)
42+
43+
If you use **Cursor**, [`.cursor/rules/README.md`](.cursor/rules/README.md) only points to **`AGENTS.md`**—same docs as everyone else.

‎skills/android/SKILL.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
---
2+
name: android
3+
description: Use for Android module layout, Gradle config, and Kotlin/Java conventions in contentstack-android.
4+
---
5+
6+
# Android project layout – contentstack-android
7+
8+
## When to use
9+
10+
- Editing `contentstack/build.gradle`, manifests, or source under `contentstack/src/`
11+
- Adjusting `minSdk`, multidex, or packaging excludes
12+
13+
## Instructions
14+
15+
### Source trees
16+
17+
- Follow standard Android library layout: **`main`**, **`test`**, **`androidTest`** under `contentstack/src/`.
18+
19+
### Configuration
20+
21+
- **`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`).
22+
23+
### Java/Kotlin
24+
25+
- Compile options target **Java 17** in the module—match language features accordingly.

‎skills/code-review/SKILL.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
---
2+
name: code-review
3+
description: Use when reviewing PRs for contentstack-android—API stability, Gradle, tests, and mobile security.
4+
---
5+
6+
# Code review – contentstack-android
7+
8+
## When to use
9+
10+
- Reviewing feature or fix PRs for the Android SDK
11+
- Auditing dependency or manifest changes
12+
13+
## Instructions
14+
15+
### Checklist
16+
17+
- **API**: Public SDK surface changes justified and documented.
18+
- **Gradle**: Version bumps coherent; no accidental signing or secret commits.
19+
- **Tests**: Unit tests for new logic; consider Robolectric limitations.
20+
- **Manifest/resources**: No unnecessary permissions; ProGuard rules updated if needed.
21+
- **Cross-SDK**: Behavior consistent with Java/Swift where applicable.
22+
23+
### Severity hints
24+
25+
- **Blocker**: Broken `:contentstack:testDebugUnitTest`, leaked credentials, or broken publish metadata.
26+
- **Major**: Missing coverage for risky network or caching changes.
27+
- **Minor**: Formatting, comments, internal refactors.

‎skills/contentstack-android-cda/SKILL.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
---
2+
name: contentstack-android-cda
3+
description: Use for the public Android Content Delivery SDK surface and package com.contentstack.sdk.
4+
---
5+
6+
# Android CDA SDK – contentstack-android
7+
8+
## When to use
9+
10+
- Changing SDK entry points consumed by Android apps
11+
- Working with stack configuration, entries, or HTTP client usage in this module
12+
13+
## Instructions
14+
15+
### Module
16+
17+
- Primary code lives in **`contentstack/`** with namespace **`com.contentstack.sdk`** (`android { namespace ... }`).
18+
19+
### API design
20+
21+
- Keep public Java/Kotlin APIs stable for app developers—use semver for breaking changes in published AARs.
22+
23+
### Integration
24+
25+
- Behavior should stay aligned with other CDA SDKs where features overlap (queries, preview, etc.)—check parity with Java/Swift docs when adding features.

‎skills/dev-workflow/SKILL.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
---
2+
name: dev-workflow
3+
description: Use for Gradle tasks, CI, release publishing, and branch flow in contentstack-android.
4+
---
5+
6+
# Development workflow – contentstack-android
7+
8+
## When to use
9+
10+
- Running local builds/tests before a PR
11+
- Aligning with GitHub Actions (branch checks, SCA, publish)
12+
13+
## Instructions
14+
15+
### Project shape
16+
17+
- Root project **`contentstack-android`** includes module **`:contentstack`** (`settings.gradle`).
18+
19+
### Commands
20+
21+
- From repo root: `./gradlew :contentstack:testDebugUnitTest` for JVM unit tests on the library.
22+
- Use `./gradlew clean` when switching branches or after AGP/cache issues.
23+
24+
### CI
25+
26+
- Workflows under `.github/workflows/` enforce policies and may publish artifacts—coordinate version bumps with `contentstack/build.gradle` `PUBLISH_*` fields.

‎skills/framework/SKILL.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
---
2+
name: framework
3+
description: Use for AGP, Gradle plugins, JaCoCo, signing, and native Android build concerns in contentstack-android.
4+
---
5+
6+
# Build & platform – contentstack-android
7+
8+
## When to use
9+
10+
- Upgrading Android Gradle Plugin, compile SDK, or dependencies
11+
- Fixing signing, packaging excludes, or multidex issues
12+
13+
## Instructions
14+
15+
### Gradle
16+
17+
- Root **`build.gradle`** pins AGP and Nexus publish plugin versions; module plugin **`com.android.library`** applies in `contentstack/build.gradle`.
18+
19+
### Publishing
20+
21+
- Maven coordinates use `PUBLISH_GROUP_ID`, `PUBLISH_ARTIFACT_ID`, `PUBLISH_VERSION`—bump with releases.
22+
23+
### Keystore
24+
25+
- Debug/release signing references **`key.keystore`** in the module—suitable for sample/debug only; production signing is consumer responsibility.

‎skills/testing/SKILL.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
---
2+
name: testing
3+
description: Use for JVM unit tests, Robolectric, AndroidX Test, and JaCoCo in contentstack-android.
4+
---
5+
6+
# Testing – contentstack-android
7+
8+
## When to use
9+
10+
- Adding tests under `contentstack/src/test/`
11+
- Debugging JaCoCo or unit-test-only failures
12+
13+
## Instructions
14+
15+
### Unit tests
16+
17+
- Prefer **`testDebugUnitTest`** for fast feedback; Robolectric enables Android APIs on JVM where configured.
18+
19+
### Instrumentation
20+
21+
- **`androidTest`** exists for on-device tests—run on emulator/CI when changing UI-adjacent or integration paths.
22+
23+
### Coverage
24+
25+
- Debug builds enable **`testCoverageEnabled`**—JaCoCo outputs feed into reporting tasks defined in the module `build.gradle`.
26+
27+
### Hygiene
28+
29+
- Use **`MockWebserver`** and fixtures for HTTP; avoid embedding real stack credentials in the repo.

0 commit comments

Comments
 (0)