Skip to content

Commit d478c5a

Browse files
reeshika-hreeshika-h
committed
Add AGENTS.md and related SKILL documentation for Contentstack Android Persistence
1 parent 76a3f2d commit d478c5a

9 files changed

Lines changed: 282 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: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
# Contentstack Android Persistence – 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/contentstack-android-persistence](https://github.com/contentstack/contentstack-android-persistence) |
10+
| *Purpose:* | Android library that persists Contentstack sync data locally using Realm, so apps can work offline with the Contentstack Android SDK. |
11+
| *Out of scope (if any):* | Does not ship a standalone HTTP client or replace the Contentstack Android SDK; persistence and sync orchestration sit on top of `com.contentstack.sdk:android` and Realm. |
12+
13+
## Tech stack (at a glance)
14+
15+
| Area | Details |
16+
| --- | --- |
17+
| Language | Java 8 (source/target compatibility); JDK 17 used in release CI (`setup-java`). |
18+
| Build | Gradle with Android Gradle Plugin 8.2.x, Realm Android plugin 10.15.x; root `build.gradle`, `settings.gradle` (`:app`), `app/build.gradle`, `gradle.properties` (Maven coordinates, signing flags). |
19+
| Tests | Android/JUnit via Gradle (`test`, `connectedAndroidTest` when present); no `src/test` or `src/androidTest` trees in this repo yet—add tests under `app/src/test/` or `app/src/androidTest/` as applicable. |
20+
| Lint / coverage | Android Lint via `./gradlew :app:lint` (default Android lint integration). |
21+
| Other | Realm (`io.realm:realm-gradle-plugin`), Maven Central publishing (`com.vanniktech.maven.publish`), Contentstack Android SDK `com.contentstack.sdk:android` (see `app/build.gradle`). |
22+
23+
## Commands (quick reference)
24+
25+
| Command Type | Command |
26+
| --- | --- |
27+
| Build | `./gradlew clean build` |
28+
| Test | `./gradlew test` (unit); `./gradlew connectedAndroidTest` (instrumented, requires device/emulator) |
29+
| Lint | `./gradlew :app:lint` |
30+
31+
**CI:** Release workflow runs `./gradlew clean build` before publish—see [.github/workflows/publish-release.yml](.github/workflows/publish-release.yml). Branch rules for `master` are in [.github/workflows/check-branch.yml](.github/workflows/check-branch.yml).
32+
33+
## Where the documentation lives: skills
34+
35+
| Skill | Path | What it covers |
36+
| --- | --- | --- |
37+
| Dev workflow | [skills/dev-workflow/SKILL.md](skills/dev-workflow/SKILL.md) | Branches, CI, Gradle commands, publishing expectations. |
38+
| Android Persistence SDK | [skills/android-persistence-sdk/SKILL.md](skills/android-persistence-sdk/SKILL.md) | Public API, Realm + Contentstack boundaries, initialization. |
39+
| Java & Android layout | [skills/java-android/SKILL.md](skills/java-android/SKILL.md) | Java conventions and module/source layout for this repo. |
40+
| Android platform & tooling | [skills/android-platform/SKILL.md](skills/android-platform/SKILL.md) | Gradle, Realm plugin, Android config, Maven publish, dependencies. |
41+
| Testing | [skills/testing/SKILL.md](skills/testing/SKILL.md) | Where to add tests, naming, and credentials policy. |
42+
| Code review | [skills/code-review/SKILL.md](skills/code-review/SKILL.md) | PR checklist and severity guidance. |
43+
44+
An index with "when to use" hints is in [skills/README.md](skills/README.md).
45+
46+
## Using Cursor (optional)
47+
48+
If you use *Cursor*, [.cursor/rules/README.md](.cursor/rules/README.md) only points to *AGENTS.md*—same docs as everyone else.

‎skills/README.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# Skills – Contentstack Android Persistence
2+
3+
Source of truth for detailed guidance. Read [AGENTS.md](../AGENTS.md) first, then open the skill that matches your task.
4+
5+
## When to use which skill
6+
7+
| Skill folder | Use when |
8+
| --- | --- |
9+
| `dev-workflow` | Branching, CI expectations, day-to-day Gradle build/test/lint, or release/publish context. |
10+
| `android-persistence-sdk` | Changing or documenting `RealmStore`, `SyncManager`, `SyncStore`, `SyncPersistable`, or how they integrate with Contentstack `Stack` / sync. |
11+
| `java-android` | Java style, packages, or where source and resources live under `app/src/main/`. |
12+
| `android-platform` | Gradle/AGP/Realm versions, `gradle.properties` coordinates, dependency bumps, or Maven publishing plugin behavior. |
13+
| `testing` | Adding unit or instrumented tests, fixtures, or policies around secrets in tests. |
14+
| `code-review` | Preparing or reviewing a PR against team expectations. |
15+
16+
Each folder contains `SKILL.md` with YAML frontmatter (`name`, `description`).

‎skills/android-persistence-sdk/SKILL.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
---
2+
name: android-persistence-sdk
3+
description: Use when changing or explaining Realm-backed persistence, sync flow, or integration with the Contentstack Android Stack API.
4+
---
5+
6+
# Android Persistence SDK – Contentstack Android Persistence
7+
8+
## When to use
9+
10+
- You edit or document `RealmStore`, `SyncManager`, `SyncStore`, `SyncPersistable`, or related persistence types under `com.contentstack.sdk.persistence`.
11+
- You need to explain how consumers initialize the library with `Stack`, `Realm`, and `SyncManager`.
12+
- You are tracing sync tokens, pagination, or error handling tied to Contentstack `Error` / sync APIs.
13+
14+
## Instructions
15+
16+
### Responsibilities
17+
18+
- Primary entry points for sync + local storage are `RealmStore` (Realm instance + storage) and `SyncManager` (`RealmStore` + `Stack`). Consumers obtain a `Stack` from `Contentstack.stack(...)`, a `Realm` instance, then construct these types as shown in the root [README.md](../../README.md).
19+
- `SyncPersistable` and model classes using Realm (`RealmModel`, `@RealmField`) define what gets persisted; keep field mapping and reflection-based `CONTENT_TYPE_CLASS_MAPPER` / `CLASS_FIELDS_MAPPER` logic consistent when adding content types.
20+
- This module **does not** reimplement network I/O; it delegates sync to the Contentstack Android SDK (`com.contentstack.sdk`). Changes that look like “REST client” or generic HTTP belong upstream, not here.
21+
22+
### Package and surface
23+
24+
- Public API lives under `app/src/main/java/com/contentstack/sdk/persistence/`. Prefer `@NonNull` and clear JavaDoc on constructors and methods intended for app developers.
25+
- Avoid breaking binary compatibility for published methods without a version strategy coordinated via `gradle.properties` / release process.
26+
27+
### Product docs
28+
29+
- End-user documentation links are in [README.md](../../README.md) (Contentstack docs, example app repo).
30+
31+
## References
32+
33+
- [java-android/SKILL.md](../java-android/SKILL.md) — source tree and Java conventions.
34+
- [android-platform/SKILL.md](../android-platform/SKILL.md) — Contentstack SDK and Realm dependency versions.
35+
- [AGENTS.md](../../AGENTS.md) — purpose and out-of-scope boundaries.

‎skills/android-platform/SKILL.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
---
2+
name: android-platform
3+
description: Use when changing Gradle/AGP/Realm versions, Android SDK levels, dependencies, or Maven Central publishing configuration.
4+
---
5+
6+
# Android platform & tooling – Contentstack Android Persistence
7+
8+
## When to use
9+
10+
- You upgrade Android Gradle Plugin, Realm plugin, `compileSdkVersion` / `minSdkVersion` / `targetSdkVersion`.
11+
- You add or bump dependencies in `app/build.gradle` or force resolutions in `configurations.all`.
12+
- You touch `mavenPublishing`, signing, or POM fields driven by `gradle.properties`.
13+
14+
## Instructions
15+
16+
### Key files
17+
18+
- Root [build.gradle](../../build.gradle): AGP and Realm Gradle plugin classpath; `clean` task.
19+
- [settings.gradle](../../settings.gradle): includes `:app` only.
20+
- [app/build.gradle](../../app/build.gradle): `com.android.library`, `realm-android`, `com.vanniktech.maven.publish`, `dependencies`, Kotlin stdlib forces (CVE-related), `mavenPublishing` block.
21+
- [gradle.properties](../../gradle.properties): `GROUP`, `POM_*`, `VERSION_NAME`, AndroidX flags, signing toggle.
22+
23+
### Android config (current baseline)
24+
25+
- `compileSdkVersion` / `targetSdkVersion` 34; `minSdkVersion` 24; Java 8 bytecode.
26+
- Realm: `io.realm:realm-gradle-plugin` version aligned with root `buildscript` classpath.
27+
28+
### Dependencies
29+
30+
- Contentstack Android SDK: `com.contentstack.sdk:android`—persistence behavior assumes that stack API.
31+
- Gson and Kotlin stdlib versions may be forced for security advisories; preserve comment context when bumping.
32+
33+
### Publishing
34+
35+
- Release CI runs `./gradlew publishAndReleaseToMavenCentral` with secrets—local changes to signing or portal IDs should stay consistent with [publish-release.yml](../../.github/workflows/publish-release.yml).
36+
37+
## References
38+
39+
- [dev-workflow/SKILL.md](../dev-workflow/SKILL.md) — commands and branch/CI expectations.
40+
- [AGENTS.md](../../AGENTS.md) — quick reference table.

‎skills/code-review/SKILL.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
---
2+
name: code-review
3+
description: Use when preparing or reviewing a pull request for this library—scope, API safety, and release impact.
4+
---
5+
6+
# Code review – Contentstack Android Persistence
7+
8+
## When to use
9+
10+
- Before requesting review or when acting as reviewer on a PR touching Java, Gradle, or CI.
11+
12+
## Instructions
13+
14+
### Checklist
15+
16+
- **Scope:** Change matches the PR description; no unrelated refactors or formatting-only churn unless agreed.
17+
- **API / compatibility:** Public classes under `com.contentstack.sdk.persistence`—consider binary compatibility and documented initialization flow ([android-persistence-sdk/SKILL.md](../android-persistence-sdk/SKILL.md)).
18+
- **Dependencies:** Version bumps justified; security-related forces (Gson, Kotlin stdlib) preserved or improved with a note in the PR.
19+
- **Build:** `./gradlew clean build` and `./gradlew :app:lint` succeed locally; new tests pass if added.
20+
- **Secrets:** No keys, tokens, or signing material committed.
21+
22+
### Severity (optional)
23+
24+
- **Blocker:** Breaks build, publish, or documented public API without version/changelog strategy; security regression.
25+
- **Major:** Behavioral sync/persistence bug, or dependency change that needs explicit consumer communication.
26+
- **Minor:** Style, logging, JavaDoc, non-user-facing cleanup.
27+
28+
## References
29+
30+
- [dev-workflow/SKILL.md](../dev-workflow/SKILL.md) — CI and branch expectations.
31+
- [AGENTS.md](../../AGENTS.md) — project purpose and commands.

‎skills/dev-workflow/SKILL.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
---
2+
name: dev-workflow
3+
description: Use when branching, running CI-aligned Gradle tasks, or coordinating releases for this Android persistence library.
4+
---
5+
6+
# Dev workflow – Contentstack Android Persistence
7+
8+
## When to use
9+
10+
- You need the canonical build, test, or lint commands.
11+
- You are opening a PR and must align with GitHub Actions and branch rules.
12+
- You are changing publishing or signing-related Gradle properties.
13+
14+
## Instructions
15+
16+
### Branches and PRs
17+
18+
- Merges into `master` from branches other than `staging` are blocked by [.github/workflows/check-branch.yml](../../.github/workflows/check-branch.yml); use the staging → master flow expected by the org unless instructed otherwise.
19+
- Other workflows cover CodeQL, policy/SCA scans, Jira linkage, and Maven snapshot/release publishing—inspect `.github/workflows/` when your change affects security scanning or release automation.
20+
21+
### Commands (local)
22+
23+
- **Full CI-like build:** `./gradlew clean build` (matches [publish-release.yml](../../.github/workflows/publish-release.yml) before publish).
24+
- **Lint:** `./gradlew :app:lint`.
25+
- **Unit tests:** `./gradlew test` once `src/test` exists.
26+
- **Instrumented tests:** `./gradlew connectedAndroidTest` with a device or emulator.
27+
28+
### Versioning and artifacts
29+
30+
- Library coordinates and version live in `gradle.properties` (`GROUP`, `POM_ARTIFACT_ID`, `VERSION_NAME`, etc.); `app/build.gradle` references `GROUP`, `POM_ARTIFACT_ID`, `VERSION_NAME` for `mavenPublishing`.
31+
- Do not bump `VERSION_NAME` or publishing metadata casually—coordinate with maintainers and release workflow secrets.
32+
33+
## References
34+
35+
- [AGENTS.md](../../AGENTS.md) — top-level stack and command table.
36+
- [android-platform/SKILL.md](../android-platform/SKILL.md) — Gradle, Realm, and Maven plugin details.
37+
- [testing/SKILL.md](../testing/SKILL.md) — test layout when adding coverage.

‎skills/java-android/SKILL.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
name: java-android
3+
description: Use for Java source layout, packages, and Android resource conventions in the app module.
4+
---
5+
6+
# Java & Android layout – Contentstack Android Persistence
7+
8+
## When to use
9+
10+
- You add or move `.java` files, packages, or Android resources.
11+
- You align new code with existing patterns (AndroidX, logging, Realm annotations).
12+
13+
## Instructions
14+
15+
### Layout
16+
17+
- Library code and any sample activity live in the single module **`app`**, namespace `com.contentstack.sdk.persistence` (see `app/build.gradle` `namespace`).
18+
- Java sources: `app/src/main/java/com/contentstack/sdk/persistence/`.
19+
- Manifest, themes, layouts: `app/src/main/AndroidManifest.xml`, `app/src/main/res/`.
20+
21+
### Language level
22+
23+
- `compileOptions` use Java 8 (`sourceCompatibility` / `targetCompatibility` `1.8`). Match that level unless the project explicitly migrates (would require Gradle and CI updates).
24+
25+
### Android patterns in this repo
26+
27+
- AndroidX artifacts are already in use (`androidx.appcompat`, Material, ConstraintLayout, Lifecycle). New UI or lifecycle code should stay on AndroidX, not legacy support libraries.
28+
- Realm types use `io.realm` APIs and annotations; follow existing `RealmModel` / `@RealmField` usage when extending persisted models.
29+
30+
## References
31+
32+
- [android-persistence-sdk/SKILL.md](../android-persistence-sdk/SKILL.md) — API and sync responsibilities.
33+
- [android-platform/SKILL.md](../android-platform/SKILL.md) — `compileSdk`, `minSdk`, and dependency versions.

‎skills/testing/SKILL.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
---
2+
name: testing
3+
description: Use when adding or running unit/instrumented tests, test data, or policies for secrets and credentials.
4+
---
5+
6+
# Testing – Contentstack Android Persistence
7+
8+
## When to use
9+
10+
- You add `src/test` or `src/androidTest` coverage.
11+
- You need conventions for naming, structure, or what must not be committed.
12+
13+
## Instructions
14+
15+
### Layout (recommended)
16+
17+
- **Unit tests:** `app/src/test/java/` mirroring package `com.contentstack.sdk.persistence` (JUnit 4/5 per project choice once added).
18+
- **Instrumented tests:** `app/src/androidTest/java/` for tests that need `Realm`, Android framework, or `Context`.
19+
20+
### Running
21+
22+
- Unit: `./gradlew test`
23+
- Instrumented: `./gradlew connectedAndroidTest` (device/emulator required).
24+
25+
### Credentials and data
26+
27+
- Do **not** commit API keys, delivery tokens, stack tokens, or org-specific Realm files. Use build-time placeholders, `local.properties`, or CI secrets—same policy as for any Contentstack SDK sample.
28+
- Prefer small fixtures (JSON snippets, in-memory Realm configuration) over live network calls in unit tests; mock or stub `Stack` / sync callbacks where feasible.
29+
30+
### Coverage
31+
32+
- No JaCoCo or coverage gate is documented in-repo; if you add reporting, document the Gradle task in [dev-workflow/SKILL.md](../dev-workflow/SKILL.md) and here.
33+
34+
## References
35+
36+
- [dev-workflow/SKILL.md](../dev-workflow/SKILL.md) — Gradle test tasks.
37+
- [android-persistence-sdk/SKILL.md](../android-persistence-sdk/SKILL.md) — behavior under test.

0 commit comments

Comments
 (0)