Skip to content

Commit 2caa9b2

Browse files
reeshika-hreeshika-h
committed
Add agent guide and development workflow documentation for Contentstack Android CDA SDK.
1 parent c59d64d commit 2caa9b2

File tree

10 files changed

+424
-0
lines changed

10 files changed

+424
-0
lines changed

‎.cursor/rules/contentstack-android-cda.mdc‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
---
2+
description: Contentstack CDA patterns – Stack/Config, HTTP, retry, callbacks, Content Delivery API
3+
globs: "contentstack/src/main/java/com/contentstack/sdk/**/*.java", "contentstack/src/main/java/com/contentstack/sdk/**/*.kt"
4+
---
5+
6+
# Contentstack Android CDA – SDK Rules
7+
8+
Apply when editing the SDK core (`com.contentstack.sdk`). Keep behavior aligned with the [Content Delivery API](https://www.contentstack.com/docs/apis/content-delivery-api/).
9+
10+
## Stack and Config
11+
12+
- **Entry point:** `Contentstack.stack(Context, apiKey, deliveryToken, environment)` returns a `Stack`. Use `Config` for optional settings (host, version, region, branch, proxy, connection pool).
13+
- **Default host:** `cdn.contentstack.io`; **API version:** `v3` (see `Config`).
14+
- **Config options:** host, version, environment, branch, region (`ContentstackRegion`), proxy, connection pool, endpoint. Set these via `Config` before building the stack.
15+
- **Region/branch:** Support `Config.setRegion()` and `Config.setBranch()` for regional and branch-specific delivery.
16+
17+
## HTTP layer
18+
19+
- **Requests** use **`CSHttpConnection`** (Volley) and/or **Retrofit** + **OkHttp** (e.g. `Stack`, `APIService`). Do not bypass these for CDA calls.
20+
- **Headers:** Use the same headers and User-Agent as the rest of the SDK (see constants and request setup in `CSHttpConnection` and Stack/APIService).
21+
- **Errors:** Map API errors to the SDK **`Error`** class and pass to **`ResultCallBack`** or equivalent callback.
22+
23+
## Retry and resilience
24+
25+
- **Retry:** Volley uses `DefaultRetryPolicy` (e.g. in `CSHttpConnection`); constants in `SDKConstant` (e.g. `TimeOutDuration`, `NumRetry`, `BackOFMultiplier`). Keep retry/timeout behavior consistent when changing the HTTP layer.
26+
27+
## Callbacks and async
28+
29+
- Use existing callback types (e.g. **`ResultCallBack`**, **`EntryResultCallBack`**, **`QueryResultsCallBack`**) for async results. Do not introduce incompatible callback signatures without considering backward compatibility.
30+
- Pass **`Error`** and response data through the same callback patterns used elsewhere in the SDK.
31+
32+
## CDA concepts
33+
34+
- **Entry,** **Query,** **Asset,** **Content Type,** **Sync** – follow existing class and method names and the CDA API semantics (query params, response parsing). When adding new CDA features, align with the official Content Delivery API documentation.

‎.cursor/rules/dev-workflow.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# Development Workflow – Contentstack Android CDA SDK
2+
3+
Use this as the standard workflow when contributing to the Android CDA SDK.
4+
5+
## Branches
6+
7+
- Use feature branches for changes (e.g. `feat/...`, `fix/...`).
8+
- Base work off the appropriate long-lived branch (e.g. `staging`, `development`) per team norms.
9+
10+
## Running tests
11+
12+
- **Unit tests:** `./gradlew :contentstack:testDebugUnitTest`
13+
- **Instrumented / connected tests:** `./gradlew :contentstack:connectedDebugAndroidTest` (device or emulator required)
14+
- **Full test pass:** `./gradlew :contentstack:testDebugUnitTest :contentstack:connectedDebugAndroidTest`
15+
- **Coverage report:** `./gradlew :contentstack:jacocoTestReport`
16+
17+
Run unit tests before opening a PR. Instrumented tests may require `local.properties` with stack credentials (see `contentstack/build.gradle` buildConfigField usage).
18+
19+
## Pull requests
20+
21+
- Ensure the build passes: `./gradlew :contentstack:assembleDebug :contentstack:testDebugUnitTest`
22+
- Follow the **code-review** rule (`.cursor/rules/code-review.mdc`) for the PR checklist.
23+
- Keep changes backward-compatible for public API; call out any breaking changes clearly.
24+
25+
## Optional: TDD
26+
27+
If the team uses TDD, follow RED–GREEN–REFACTOR when adding behavior. The **testing** rule and **skills/testing** skill describe test structure and naming.

‎.cursor/rules/java.mdc‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
---
2+
description: Java/Kotlin style and com.contentstack.sdk conventions for the Android CDA SDK
3+
globs: "**/*.java", "**/*.kt"
4+
---
5+
6+
# Java / Kotlin Standards – Contentstack Android CDA SDK
7+
8+
Apply these conventions when editing Java (or Kotlin) code in this repository.
9+
10+
## Language and runtime
11+
12+
- **Java:** Target **Java 8** compatibility for the library (see `contentstack/build.gradle` compileOptions). Avoid language or API features that require a higher version without updating the module.
13+
- **Kotlin:** If present, follow existing Kotlin style and interop with `com.contentstack.sdk`; prefer null-safety and idiomatic Kotlin where it does not break public API.
14+
- Avoid raw types; use proper generics where applicable.
15+
16+
## Package and layout
17+
18+
- All SDK code lives under **`com.contentstack.sdk`** (see `contentstack/src/main/java/com/contentstack/sdk/`).
19+
- Keep the existing package structure; do not introduce new top-level packages without alignment with the rest of the SDK.
20+
21+
## Naming
22+
23+
- **Classes:** PascalCase (e.g. `CSHttpConnection`, `Config`).
24+
- **Methods/variables:** camelCase.
25+
- **Constants:** UPPER_SNAKE_CASE (e.g. in `SDKConstant`, `ErrorMessages`).
26+
- **Test classes:** `Test*` for unit tests; instrumented tests in `androidTest` (see **testing.mdc**).
27+
28+
## Logging
29+
30+
- Use **Android `Log`** or project logging as in `CSHttpConnection` (TAG-based). Obtain loggers with a class-named TAG.
31+
- Log at appropriate levels (e.g. `Log.w` for recoverable issues, `Log.d` for debug).
32+
33+
## Null-safety and annotations
34+
35+
- Use **`@NonNull`** / **`@Nullable`** (Android or JetBrains) where the project already does, to document nullability for public API.
36+
- Validate or document parameters for public methods where NPEs would be surprising.
37+
38+
## General
39+
40+
- Prefer immutability where practical (e.g. final fields, defensive copies for collections).
41+
- Document public API with Javadoc; keep examples in Javadoc in sync with actual usage (e.g. `Contentstack.stack(...)`, `Config`).

‎.cursor/rules/testing.mdc‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
description: JUnit 4, Robolectric, androidTest, test naming, JaCoCo
3+
globs: "contentstack/src/test/**/*.java", "contentstack/src/test/**/*.kt", "contentstack/src/androidTest/**/*.java", "contentstack/src/androidTest/**/*.kt"
4+
---
5+
6+
# Testing Rules – Contentstack Android CDA SDK
7+
8+
Apply when writing or editing tests. The project uses **JUnit 4**, **Robolectric** (unit), **AndroidX Test** / **Espresso** (instrumented), and **JaCoCo** (see `contentstack/build.gradle`).
9+
10+
## Test naming and layout
11+
12+
- **Unit tests:** Class name prefix **`Test`** (e.g. `TestEntry`, `TestStack`). Place in `contentstack/src/test/java/com/contentstack/sdk/`.
13+
- **Instrumented tests:** Place in `contentstack/src/androidTest/java/com/contentstack/sdk/`. Use **AndroidJUnitRunner**; naming may use `*TestCase` or `Test*` as in the project (e.g. `AssetTestCase`, `EntryTestCase`).
14+
15+
## JUnit 4 usage
16+
17+
- Use **JUnit 4** APIs: `@Test`, `@Before`, `@After`, `@BeforeClass`, `@AfterClass`.
18+
- Use **assertions** from `org.junit.Assert` (e.g. `assertEquals`, `assertNotNull`).
19+
- For unit tests on JVM, **Robolectric** provides Android context; use `Robolectric.buildService(...)` or equivalent where a Context is needed.
20+
21+
## Unit vs instrumented
22+
23+
- **Unit tests** (`src/test/`): Run on JVM with Robolectric; use **MockWebServer** (OkHttp) for HTTP when appropriate; mock dependencies with Mockito/PowerMock as needed.
24+
- **Instrumented tests** (`src/androidTest/`): Run on device/emulator; may use real stack credentials from `BuildConfig` / `local.properties`; avoid flakiness (timeouts, IdlingResource if using Espresso).
25+
26+
## Test data and credentials
27+
28+
- **Credentials:** Instrumented tests may use `BuildConfig` fields (APIKey, deliveryToken, environment, host) populated from `local.properties`. Do not commit real tokens; document required keys in README or test docs.
29+
- **Fixtures:** Use existing test assets and JSON under `src/test/` where applicable.
30+
31+
## Coverage
32+
33+
- **JaCoCo** is configured in `contentstack/build.gradle`. Run `./gradlew :contentstack:jacocoTestReport` for unit-test coverage (e.g. `contentstack/build/reports/jacoco/`). Maintain or improve coverage when adding or changing production code.

‎AGENTS.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
# Contentstack Android CDA SDK – Agent Guide
2+
3+
This document is the main entry point for AI agents working in this repository.
4+
5+
## Project
6+
7+
- **Name:** Contentstack Android CDA SDK (contentstack-android)
8+
- **Purpose:** Android client for the Contentstack **Content Delivery API (CDA)**. It fetches content (entries, assets, content types, sync, etc.) from Contentstack for Android apps.
9+
- **Repo:** [contentstack-android](https://github.com/contentstack/contentstack-android)
10+
11+
## Tech stack
12+
13+
- **Languages:** Java (primary SDK source); Kotlin may appear in tests or future code. Target **Java 8** compatibility for the library (see `contentstack/build.gradle`).
14+
- **Build:** Gradle (Android Gradle Plugin), single module **`contentstack`** (AAR).
15+
- **Testing:** JUnit 4, Robolectric (unit tests on JVM), Mockito / PowerMock where used; **androidTest** with AndroidX Test / Espresso for instrumented tests; JaCoCo for coverage (`jacocoTestReport`).
16+
- **HTTP:** **Volley** (`CSHttpConnection`) for much of the CDA traffic; **Retrofit 2 + OkHttp + Gson** for paths such as taxonomy (`Stack`, `APIService`). OkHttp **MockWebServer** in unit tests.
17+
18+
## Main entry points
19+
20+
- **`Contentstack`** – Factory: `Contentstack.stack(Context, apiKey, deliveryToken, environment)` (and overloads with `Config`) returns a **`Stack`**.
21+
- **`Stack`** – Main API: content types, entries, queries, assets, sync, etc.
22+
- **`Config`** – Optional configuration: host, version, region, branch, proxy, connection pool, endpoint.
23+
- **Paths:** `contentstack/src/main/java/com/contentstack/sdk/` (production), `contentstack/src/test/java/com/contentstack/sdk/` (unit tests), `contentstack/src/androidTest/java/` (instrumented tests).
24+
25+
## Commands
26+
27+
Run from the **repository root** (requires Android SDK / `local.properties` for connected tests).
28+
29+
| Goal | Command |
30+
|------|---------|
31+
| **Build library (debug)** | `./gradlew :contentstack:assembleDebug` |
32+
| **Run all unit tests** | `./gradlew :contentstack:testDebugUnitTest` |
33+
| **Run instrumented / connected tests** | `./gradlew :contentstack:connectedDebugAndroidTest` (device or emulator required) |
34+
| **Unit + connected (full local test pass)** | `./gradlew :contentstack:testDebugUnitTest :contentstack:connectedDebugAndroidTest` |
35+
| **Coverage report (unit)** | `./gradlew :contentstack:jacocoTestReport` |
36+
37+
Instrumented tests may need **`local.properties`** entries (e.g. `APIKey`, `deliveryToken`, `environment`, `host`) for stacks that hit a real CDA endpoint—see `contentstack/build.gradle` `buildConfigField` usage.
38+
39+
## Rules and skills
40+
41+
- **`.cursor/rules/`** – Cursor rules for this repo:
42+
- **README.md** – Index of all rules (globs / always-on).
43+
- **dev-workflow.md** – Branches, tests, PR expectations.
44+
- **java.mdc** – Applies to `**/*.java` and `**/*.kt`: language style, `com.contentstack.sdk` layout, logging, null-safety.
45+
- **contentstack-android-cda.mdc** – SDK core: CDA patterns, Stack/Config, host/version/region/branch, retry, callbacks, CDA alignment.
46+
- **testing.mdc** – `contentstack/src/test/**` and `contentstack/src/androidTest/**`: naming, unit vs instrumented, JaCoCo.
47+
- **code-review.mdc** – Always applied: PR/review checklist (aligned with Java CDA SDK).
48+
- **`skills/`** – Reusable skill docs:
49+
- **contentstack-android-cda** – Implementing or changing CDA behavior (Stack/Config, entries, assets, sync, HTTP, callbacks).
50+
- **testing** – Writing or refactoring tests.
51+
- **code-review** – PR review / pre-PR checklist.
52+
- **framework** – Config, HTTP layer (Volley + Retrofit/OkHttp), retry/timeouts.
53+
54+
Refer to `.cursor/rules/README.md` and `skills/README.md` for details.

‎skills/README.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# Skills – Contentstack Android CDA SDK
2+
3+
This directory contains **skills**: reusable guidance for AI agents (and developers) on specific tasks. Each skill is a folder with a `SKILL.md` file.
4+
5+
## When to use which skill
6+
7+
| Skill | Use when |
8+
|-------|----------|
9+
| **contentstack-android-cda** | Implementing or changing CDA features: Stack/Config, entries, assets, content types, sync, HTTP layer (Volley + Retrofit/OkHttp), callbacks, error handling. |
10+
| **testing** | Writing or refactoring tests: JUnit 4, Robolectric, androidTest, naming, MockWebServer, JaCoCo. |
11+
| **code-review** | Reviewing a PR or preparing your own: API design, null-safety, exceptions, backward compatibility, dependencies/security, test coverage. |
12+
| **framework** | Touching config or the HTTP layer: Config options, CSHttpConnection (Volley), Stack/APIService (Retrofit/OkHttp), timeouts/retry, error handling. |
13+
14+
## How agents should use skills
15+
16+
- **contentstack-android-cda:** Apply when editing SDK core (`com.contentstack.sdk`) or adding CDA-related behavior. Follow Stack/Config, CDA API alignment, and existing callback/error patterns.
17+
- **testing:** Apply when creating or modifying test classes. Follow naming (`Test*` for unit tests), Robolectric vs androidTest, and existing Gradle/JaCoCo setup.
18+
- **code-review:** Apply when performing or simulating a PR review. Go through the checklist (API stability, errors, compatibility, dependencies, tests) and optional severity levels.
19+
- **framework:** Apply when changing Config, CSHttpConnection, Stack’s Retrofit/OkHttp setup, or retry/timeout constants. Keep behavior consistent with the rest of the SDK.
20+
21+
Each skill’s `SKILL.md` contains more detailed instructions and references.

‎skills/code-review/SKILL.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
---
2+
name: code-review
3+
description: Use when reviewing PRs or before opening a PR – API design, null-safety, exceptions, backward compatibility, dependencies, security, and test quality
4+
---
5+
6+
# Code Review – Contentstack Android CDA SDK
7+
8+
Use this skill when performing or preparing a pull request review for the Android CDA SDK. Aligns with the Java CDA SDK review bar.
9+
10+
## When to use
11+
12+
- Reviewing someone else’s PR.
13+
- Self-reviewing your own PR before submission.
14+
- Checking that changes meet project standards (API, errors, compatibility, tests, security).
15+
16+
## Instructions
17+
18+
Work through the checklist below. Optionally tag items with severity: **Blocker**, **Major**, **Minor**.
19+
20+
### 1. API design and stability
21+
22+
- [ ] **Public API:** New or changed public methods/classes are necessary and documented (Javadoc with purpose and, where relevant, params/returns).
23+
- [ ] **Backward compatibility:** No breaking changes to public API unless explicitly agreed (e.g. major version). Deprecations should have alternatives and timeline.
24+
- [ ] **Naming:** Consistent with existing SDK style and CDA terminology (e.g. `Stack`, `Entry`, `Query`, `Config`).
25+
26+
**Severity:** Breaking public API without approval = Blocker. Missing docs on new public API = Major.
27+
28+
### 2. Error handling and robustness
29+
30+
- [ ] **Errors:** API failures are mapped to the SDK `Error` type and passed through existing callback/result patterns (e.g. `ResultCallBack`).
31+
- [ ] **Null safety:** No unintended NPEs; document or validate parameters for public API where it matters.
32+
- [ ] **Exceptions:** Checked exceptions are handled or declared; use of unchecked exceptions is intentional and documented where relevant.
33+
34+
**Severity:** Wrong or missing error handling in new code = Major.
35+
36+
### 3. Dependencies and security
37+
38+
- [ ] **Dependencies:** New or upgraded dependencies are justified. Version bumps are intentional and do not introduce known vulnerabilities.
39+
- [ ] **SCA:** Any security findings (e.g. Snyk, Dependabot) in the change set are addressed or explicitly deferred with a ticket.
40+
41+
**Severity:** New critical/high vulnerability = Blocker.
42+
43+
### 4. Testing
44+
45+
- [ ] **Coverage:** New or modified behavior has corresponding unit and/or instrumented tests.
46+
- [ ] **Conventions:** Tests follow naming (`Test*` for unit tests) and live in `src/test/` or `src/androidTest/` as appropriate.
47+
- [ ] **Quality:** Tests are readable, deterministic (no flakiness), and assert meaningful behavior.
48+
49+
**Severity:** No tests for new behavior = Blocker. Flaky or weak tests = Major.
50+
51+
### 5. Optional severity summary
52+
53+
- **Blocker:** Must fix before merge (e.g. breaking API without approval, security issue, no tests for new code).
54+
- **Major:** Should fix (e.g. inconsistent error handling, missing Javadoc on new public API, flaky tests).
55+
- **Minor:** Nice to fix (e.g. style, minor docs, redundant code).
56+
57+
## References
58+
59+
- Project rule: `.cursor/rules/code-review.mdc`
60+
- Testing skill: `skills/testing/SKILL.md` for test standards

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

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
---
2+
name: contentstack-android-cda
3+
description: Use when implementing or changing CDA features – Stack/Config, entries, assets, sync, HTTP, callbacks, and Content Delivery API alignment
4+
---
5+
6+
# Contentstack Android CDA SDK – CDA Implementation
7+
8+
Use this skill when implementing or changing Content Delivery API (CDA) behavior in the Android SDK.
9+
10+
## When to use
11+
12+
- Adding or modifying Stack, Entry, Query, Asset, Content Type, or Sync behavior.
13+
- Changing Config options (host, version, region, branch, proxy, connection pool).
14+
- Working with the HTTP layer (CSHttpConnection/Volley, Stack/APIService/Retrofit/OkHttp) or callbacks and Error handling.
15+
16+
## Instructions
17+
18+
### Stack and Config
19+
20+
- **Entry point:** `Contentstack.stack(Context, apiKey, deliveryToken, environment)`. Overloads accept `Config` for host, version, region, branch, proxy, connection pool, endpoint.
21+
- **Defaults:** host `cdn.contentstack.io`, version `v3` (see `Config`). Region and branch via `Config.setRegion()`, `Config.setBranch()`.
22+
- **Reference:** `Contentstack.java`, `Stack.java`, `Config.java`.
23+
24+
### CDA resources
25+
26+
- **Entries:** `Stack.contentType(uid).entry(uid)`, query APIs, and entry fetch. Use existing `Entry`, `Query`, `EntriesModel`, and callback types.
27+
- **Assets:** `Stack.assetLibrary()`, asset fetch and query. Use `Asset`, `AssetLibrary`, `AssetModel`, and related callbacks.
28+
- **Content types:** Content type schema and listing. Use `ContentType`, `ContentTypesModel`, `ContentTypesCallback`.
29+
- **Sync:** Sync API usage. Use existing sync request/response and pagination patterns.
30+
- **Official API:** Align with [Content Delivery API](https://www.contentstack.com/docs/apis/content-delivery-api/) for parameters, response shape, and semantics.
31+
32+
### HTTP and retry
33+
34+
- **HTTP:** CDA requests use **CSHttpConnection** (Volley) and/or **Retrofit** + **OkHttp** (e.g. `Stack`, `APIService`). Set headers (User-Agent, auth) per constants and existing request building.
35+
- **Retry:** Volley retry is configured via `DefaultRetryPolicy` in `CSHttpConnection`; constants in `SDKConstant` (e.g. `TimeOutDuration`, `NumRetry`, `BackOFMultiplier`). Keep timeouts and retry behavior consistent when changing the HTTP layer.
36+
- **Reference:** `CSHttpConnection.java`, `CSConnectionRequest.java`, `Stack.java`, `APIService.java`, `SDKConstant.java`.
37+
38+
### Errors and callbacks
39+
40+
- **Errors:** Map API errors to the `Error` class. Pass to the appropriate callback (e.g. `ResultCallBack`) so callers receive a consistent error shape.
41+
- **Callbacks:** Use existing callback types (`ResultCallBack`, `EntryResultCallBack`, `QueryResultsCallBack`, etc.). Do not change callback contracts without considering backward compatibility.
42+
43+
## Key classes
44+
45+
- **Entry points:** `Contentstack`, `Stack`, `Config`
46+
- **CDA:** `Entry`, `Query`, `Asset`, `AssetLibrary`, `ContentType`, sync-related classes
47+
- **HTTP:** `CSHttpConnection`, `CSConnectionRequest`, `APIService`, `Stack` (Retrofit)
48+
- **Errors / results:** `Error`, `QueryResult`, and callback interfaces in `com.contentstack.sdk`
49+
50+
## References
51+
52+
- [Content Delivery API – Contentstack Docs](https://www.contentstack.com/docs/apis/content-delivery-api/)
53+
- Project rules: `.cursor/rules/contentstack-android-cda.mdc`, `.cursor/rules/java.mdc`

0 commit comments

Comments
 (0)