Skip to content

Commit 78a6bac

Browse files
reeshika-hreeshika-h
committed
Add AGENTS.md and related SKILL documentation for Contentstack IOS Persistence
1 parent 1c730e7 commit 78a6bac

File tree

9 files changed

+329
-0
lines changed

9 files changed

+329
-0
lines changed

‎.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 iOS 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:* | https://github.com/contentstack/contentstack-ios-persistence |
10+
| *Purpose:* | iOS library that persists Contentstack sync data locally so apps can work offline. Ships a shared core plus Core Data and Realm adapters consumed via CocoaPods. |
11+
| *Out of scope (if any):* | Not a standalone HTTP client; network and sync protocol come from the **Contentstack** iOS SDK dependency. Does not ship the example app (see [contentstack-ios-persistence-example](https://github.com/contentstack/contentstack-ios-persistence-example)). |
12+
13+
## Tech stack (at a glance)
14+
15+
| Area | Details |
16+
| --- | --- |
17+
| Language | Objective-C (primary); Swift-compatible module imports documented in README. iOS deployment target **12.0** (see podspecs). |
18+
| Build | **Xcode** workspace `ContentstackPersistence.xcworkspace`; **CocoaPods** (`Podfile`, `pod install`). Key sources: `ContentstackPersistence/`, `ContentstackPersistenceCoredata/`, `ContentstackPersistenceRealm/`. Podspecs: `ContentstackPersistence.podspec`, `ContentstackPersistenceCoreData.podspec`, `ContentstackPersistenceRealm.podspec`. |
19+
| Tests | **XCTest** target `ContentstackPersistenceTests`; tests under `ContentstackPersistenceTests/`. |
20+
| Lint / coverage | No SwiftLint / shared coverage config in-repo; follow team standards if added later. |
21+
| Other | Dependencies: **Contentstack** iOS SDK, **Realm** (Realm subspec). Optional persistence: Core Data vs Realm via separate pods. |
22+
23+
## Commands (quick reference)
24+
25+
| Command Type | Command |
26+
| --- | --- |
27+
| Build | `pod install` then `xcodebuild -workspace ContentstackPersistence.xcworkspace -scheme ContentstackPersistence -sdk iphonesimulator build` |
28+
| Test | `xcodebuild -workspace ContentstackPersistence.xcworkspace -scheme ContentstackPersistence -destination 'platform=iOS Simulator,name=iPhone 16' test` (adjust simulator name to one installed locally) |
29+
| Lint | *(none configured)* |
30+
31+
**CI:** PR checks include branch policy (`.github/workflows/check-branch.yml`), Snyk SCA (`.github/workflows/sca-scan.yml`), and policy scans (`.github/workflows/policy-scan.yml`). Jira linkage: `.github/workflows/issues-jira.yml`.
32+
33+
## Where the documentation lives: skills
34+
35+
| Skill | Path | What it covers |
36+
| --- | --- | --- |
37+
| Dev workflow & CI | [skills/dev-workflow/SKILL.md](skills/dev-workflow/SKILL.md) | Branches, build/test, PR expectations, CI overview |
38+
| SDK & public API | [skills/contentstack-ios-persistence-sdk/SKILL.md](skills/contentstack-ios-persistence-sdk/SKILL.md) | Entry points, pods, sync/persistence boundaries, versioning |
39+
| Objective-C / Swift & layout | [skills/objc-swift-ios/SKILL.md](skills/objc-swift-ios/SKILL.md) | Language conventions and repository layout |
40+
| Testing | [skills/testing/SKILL.md](skills/testing/SKILL.md) | XCTest layout, naming, fixtures, secrets |
41+
| Code review | [skills/code-review/SKILL.md](skills/code-review/SKILL.md) | PR checklist for this repo |
42+
| iOS platform & packaging | [skills/ios-persistence-platform/SKILL.md](skills/ios-persistence-platform/SKILL.md) | CocoaPods, Core Data, Realm, Xcode workspace |
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 iOS 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, PRs to `master`/`next`, CI expectations, local build and test commands |
10+
| contentstack-ios-persistence-sdk | Changing public API, `SyncManager`, stores, podspecs, or integration with Contentstack SDK |
11+
| objc-swift-ios | Objective-C/Swift style, file layout, headers, and module boundaries in this repo |
12+
| testing | Adding or changing XCTest code, test data, or simulator-only concerns |
13+
| code-review | Reviewing or preparing a PR against this repository’s expectations |
14+
| ios-persistence-platform | CocoaPods, Realm vs Core Data, Xcode workspace/schemes, iOS deployment targets |
15+
16+
Each folder contains `SKILL.md` with YAML frontmatter (`name`, `description`).

‎skills/code-review/SKILL.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
---
2+
name: code-review
3+
description: PR checklist and severity guidance for contentstack-ios-persistence changes
4+
---
5+
6+
# Code review – Contentstack iOS Persistence
7+
8+
## When to use
9+
10+
- You are reviewing a PR or preparing one for this repository
11+
- You need a consistent checklist aligned with CI and product boundaries
12+
13+
## Instructions
14+
15+
### Before you approve
16+
17+
- **Branch policy:** Confirm the PR meets `.github/workflows/check-branch.yml` expectations (merges to `master` from `next` where required).
18+
- **Build:** Workspace builds after `pod install`; all three podspec-relevant targets remain consistent if core APIs changed.
19+
- **Tests:** New behavior has XCTest coverage where practical; no committed secrets.
20+
- **Pods:** `Podfile` / `Podfile.lock` changes are intentional; dependency ranges in podspecs match release intent.
21+
- **Docs:** User-visible API or setup changes update [README.md](../../README.md) or product docs links as needed.
22+
- **Security / compliance:** No credentials in code; Talisman-sensitive files respected.
23+
24+
### Optional severity (for discussion)
25+
26+
| Level | Examples |
27+
| --- | --- |
28+
| **Blocker** | Breaks consumers’ public API without semver major plan; security issue; build broken |
29+
| **Major** | Missing tests for risky logic; incorrect podspec dependency; sync/data loss risk |
30+
| **Minor** | Style nits, non-user-facing refactors, doc typos |
31+
32+
### CODEOWNERS
33+
34+
- Follow [CODEOWNERS](../../CODEOWNERS) for required reviewers.
35+
36+
## References
37+
38+
- [dev-workflow](../dev-workflow/SKILL.md)
39+
- [testing](../testing/SKILL.md)
40+
- [contentstack-ios-persistence-sdk](../contentstack-ios-persistence-sdk/SKILL.md)

‎skills/contentstack-ios-persistence-sdk/SKILL.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
---
2+
name: contentstack-ios-persistence-sdk
3+
description: Public API, SyncManager, Core Data and Realm stores, pod boundaries for iOS persistence
4+
---
5+
6+
# Contentstack iOS Persistence SDK – Contentstack iOS Persistence
7+
8+
## When to use
9+
10+
- You change **`SyncManager`**, **`PersistenceModel`**, **`SyncPersistable`**, **`SyncProtocol`**, or store implementations
11+
- You edit **podspecs** or dependency ranges (`Contentstack`, `Realm`)
12+
- You need to explain how this library relates to the **Contentstack** iOS SDK and sync
13+
14+
## Instructions
15+
16+
### What this library owns
17+
18+
- **Core framework** (`ContentstackPersistence/`): shared types and **`SyncManager`** orchestration; depends on **Contentstack** for stack/sync, not on Realm/Core Data directly in the base podspec.
19+
- **Core Data path** (`ContentstackPersistenceCoredata/` + `ContentstackPersistenceCoreData.podspec`): **`CoreDataStore`** and Core Data–backed persistence.
20+
- **Realm path** (`ContentstackPersistenceRealm/` + `ContentstackPersistenceRealm.podspec`): **`RealmStore`** and Realm-backed persistence; adds an explicit **Realm** dependency range in the podspec.
21+
22+
### Public surface
23+
24+
- Umbrella / public headers are declared per podspec (`s.public_header_files`); keep Objective-C headers stable for binary compatibility expectations in downstream apps.
25+
- **`SyncManager`** is the main integration point: constructed with a **Stack** (from Contentstack SDK) and a store conforming to the persistence abstraction (`CoreDataStore`, `RealmStore`, etc.).
26+
- **`PersistenceModel`** maps sync stack, assets, and entry types when customizing what gets persisted.
27+
28+
### Boundaries
29+
30+
- **In scope:** Local persistence adapters, sync callback handling, model mapping for offline storage.
31+
- **Out of scope:** Implementing REST/CDA calls here—that lives in **Contentstack**; this repo consumes **Stack** and sync flows from that SDK.
32+
33+
### Versioning
34+
35+
- Bump **`s.version`** consistently across podspecs when releasing; **`s.source`** `:tag` should match your git tagging convention (e.g. `v0.1.1`).
36+
- Subspecs depend on **`ContentstackPersistence`** with a matching semver range—keep those constraints coherent when you change the core.
37+
38+
## References
39+
40+
- [README.md](../../README.md) — integration examples (Objective-C and Swift)
41+
- [objc-swift-ios](../objc-swift-ios/SKILL.md)
42+
- [ios-persistence-platform](../ios-persistence-platform/SKILL.md)
43+
- [Contentstack iOS Persistence docs](https://www.contentstack.com/docs/guide/synchronization/using-realm-persistence-library-with-ios-sync-sdk)
44+
- [Content Delivery API](https://www.contentstack.com/docs/apis/content-delivery-api/)

‎skills/dev-workflow/SKILL.md‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
---
2+
name: dev-workflow
3+
description: Branch policy, CI, and local build/test commands for contentstack-ios-persistence
4+
---
5+
6+
# Dev workflow – Contentstack iOS Persistence
7+
8+
## When to use
9+
10+
- You are opening a PR, choosing a base branch, or interpreting CI failures
11+
- You need the canonical `pod install` / `xcodebuild` commands for this repo
12+
- You want release or versioning expectations (podspecs, tags)
13+
14+
## Instructions
15+
16+
### Branches and PRs
17+
18+
- **Default branch workflow:** `.github/workflows/check-branch.yml` blocks merging into `master` unless the PR branch is `next`. For changes targeting `master`, open PRs **from** `next` as described in that workflow’s message.
19+
- Use **CODEOWNERS** for required reviewers when present.
20+
21+
### Local development
22+
23+
1. Install pods: `pod install` from the repo root (generates/updates `Pods/` and integrates with the workspace).
24+
2. Open **`ContentstackPersistence.xcworkspace`** (not the `.xcodeproj` alone) when working with CocoaPods.
25+
26+
### Build and test
27+
28+
- **Build:** `xcodebuild -workspace ContentstackPersistence.xcworkspace -scheme ContentstackPersistence -sdk iphonesimulator build`
29+
- **Test:** `xcodebuild -workspace ContentstackPersistence.xcworkspace -scheme ContentstackPersistence -destination 'platform=iOS Simulator,name=iPhone 16' test` — pick a simulator that exists on your Mac.
30+
31+
### CI (GitHub Actions)
32+
33+
- **Branch check:** `.github/workflows/check-branch.yml` — PRs to `master` from branches other than `next` fail by policy.
34+
- **SCA:** `.github/workflows/sca-scan.yml` — Snyk `snyk test` on PRs (requires `SNYK_TOKEN` in org secrets).
35+
- **Policy:** `.github/workflows/policy-scan.yml` — public repos: `SECURITY.md` and license file with current year.
36+
- **Issues:** `.github/workflows/issues-jira.yml` — Jira integration for issues.
37+
38+
### Versioning and release hints
39+
40+
- Three podspecs at repo root must stay aligned when you bump versions: `ContentstackPersistence.podspec`, `ContentstackPersistenceCoreData.podspec`, `ContentstackPersistenceRealm.podspec` (see `s.version` and `s.source` tag).
41+
- **Talisman:** `.talismanrc` may apply to pre-commit secret scanning; do not commit API keys or tokens.
42+
43+
## References
44+
45+
- [AGENTS.md](../../AGENTS.md)
46+
- [contentstack-ios-persistence-sdk](../contentstack-ios-persistence-sdk/SKILL.md)
47+
- [testing](../testing/SKILL.md)
48+
- [ios-persistence-platform](../ios-persistence-platform/SKILL.md)

‎skills/ios-persistence-platform/SKILL.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
---
2+
name: ios-persistence-platform
3+
description: CocoaPods, Xcode workspace, Realm vs Core Data, and iOS deployment for this repo
4+
---
5+
6+
# iOS persistence platform – Contentstack iOS Persistence
7+
8+
## When to use
9+
10+
- You change **CocoaPods** integration (`Podfile`, `Podfile.lock`, podspecs)
11+
- You choose or explain **Realm** vs **Core Data** delivery paths
12+
- You adjust **iOS deployment target** or linker settings (`OTHER_LDFLAGS`, etc.)
13+
14+
## Instructions
15+
16+
### CocoaPods
17+
18+
- **Install:** `pod install` from repo root; open **`ContentstackPersistence.xcworkspace`**.
19+
- **Consumable pods:** `ContentstackPersistence` (core), `ContentstackPersistenceCoreData`, `ContentstackPersistenceRealm` — see [README.md](../../README.md) for `Podfile` lines.
20+
- **Lockfile:** Commit `Podfile.lock` when dependency resolution should be reproducible for CI or the team (follow existing repo practice).
21+
22+
### Realm vs Core Data
23+
24+
- **Realm:** `ContentstackPersistenceRealm` pod; depends on **Realm** (see `ContentstackPersistenceRealm.podspec`); implementation in `ContentstackPersistenceRealm/`.
25+
- **Core Data:** `ContentstackPersistenceCoreData` pod; no Realm dependency; implementation in `ContentstackPersistenceCoredata/`.
26+
- **Core** pod `ContentstackPersistence` is shared; apps pick one persistence backend or structure their app module graph accordingly.
27+
28+
### Xcode
29+
30+
- **Scheme:** Use `ContentstackPersistence` for build/test of the main framework (scheme may be generated in Xcode if not checked in—create/share schemes if the team standardizes on committed schemes).
31+
- **SDK:** `iphonesimulator` for typical local builds; device builds when validating arm64/device-only issues.
32+
33+
### Deployment target
34+
35+
- Podspecs specify **`s.ios.deployment_target = '12.0'`** — keep podspecs aligned when raising the minimum iOS version.
36+
37+
### Contentstack SDK
38+
39+
- Base dependency on **Contentstack** iOS SDK with ranges in podspecs (`~> 3.12` core / Core Data, `~> 3.6` Realm podspec for historical range—verify compatibility when bumping).
40+
41+
## References
42+
43+
- [contentstack-ios-persistence-sdk](../contentstack-ios-persistence-sdk/SKILL.md)
44+
- [dev-workflow](../dev-workflow/SKILL.md)
45+
- [Example app (external)](https://github.com/contentstack/contentstack-ios-persistence-example)

‎skills/objc-swift-ios/SKILL.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
---
2+
name: objc-swift-ios
3+
description: Objective-C-first layout, headers, and Swift interop for this iOS persistence repo
4+
---
5+
6+
# Objective-C / Swift & repo layout – Contentstack iOS Persistence
7+
8+
## When to use
9+
10+
- You add or rename `.h` / `.m` files under `ContentstackPersistence/`, `ContentstackPersistenceCoredata/`, or `ContentstackPersistenceRealm/`
11+
- You expose symbols to Swift consumers (`@import` / `import` patterns in README)
12+
- You align with existing naming and module structure
13+
14+
## Instructions
15+
16+
### Language
17+
18+
- **Primary implementation language:** Objective-C (`.m` / `.h`).
19+
- **Swift:** Documented in [README.md](../../README.md) via module imports; keep public APIs Objective-C–friendly (`NS_SWIFT_NAME` only if you introduce names that need Swift polish—follow existing project style).
20+
21+
### Layout (by folder)
22+
23+
| Path | Role |
24+
| --- | --- |
25+
| `ContentstackPersistence/` | Core framework: `SyncManager`, `PersistenceModel`, protocols, umbrella `ContentstackPersistence.h` |
26+
| `ContentstackPersistenceCoredata/` | Core Data store implementation |
27+
| `ContentstackPersistenceRealm/` | Realm store implementation |
28+
| `ContentstackPersistenceTests/` | XCTest sources |
29+
30+
### Headers and modules
31+
32+
- Public API is driven by **`s.public_header_files`** in each podspec—new public headers must be listed there.
33+
- Keep umbrella / main header includes predictable; consumers may use `#import <Module/Module.h>` or `@import Module`.
34+
35+
### Naming and style
36+
37+
- Match existing patterns: Objective-C naming, file names aligned with class names (e.g. `SyncManager.h` / `SyncManager.m`).
38+
- Avoid drive-by reformatting unrelated code in the same change as feature work.
39+
40+
## References
41+
42+
- [contentstack-ios-persistence-sdk](../contentstack-ios-persistence-sdk/SKILL.md)
43+
- [testing](../testing/SKILL.md)

‎skills/testing/SKILL.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
---
2+
name: testing
3+
description: XCTest layout, simulator runs, and secrets policy for ContentstackPersistenceTests
4+
---
5+
6+
# Testing – Contentstack iOS Persistence
7+
8+
## When to use
9+
10+
- You add or change tests under `ContentstackPersistenceTests/`
11+
- You run tests locally or debug CI test failures
12+
- You need guidance on credentials and fixtures
13+
14+
## Instructions
15+
16+
### Runner and location
17+
18+
- **Framework:** XCTest (`ContentstackPersistenceTests.m` and future `*Tests.m` files).
19+
- **Target:** `ContentstackPersistenceTests` (xctest bundle `ContentstackPersistenceTests.xctest`).
20+
- **Run:** After `pod install`, use `xcodebuild` with scheme `ContentstackPersistence` and action `test`, with an iOS Simulator destination (see [AGENTS.md](../../AGENTS.md)).
21+
22+
### Naming and structure
23+
24+
- Test class inherits from `XCTestCase`; methods follow `- (void)test*` naming.
25+
- Prefer descriptive test names that state what is being verified (replace placeholder `testExample` when adding real coverage).
26+
27+
### Credentials and data
28+
29+
- **Do not** commit API keys, delivery tokens, or stack secrets to tests or repo files.
30+
- Prefer mocks, dependency injection at the store/sync boundaries, or local fixtures checked in without secrets.
31+
- If integration tests against a real stack are ever added, isolate them behind explicit schemes or skipped-by-default targets and load credentials from the environment or ignored local config—not from git.
32+
33+
### Coverage
34+
35+
- No shared coverage gate is defined in-repo; if the team adds Xcode coverage or a script, document the command in [dev-workflow](../dev-workflow/SKILL.md) and [AGENTS.md](../../AGENTS.md).
36+
37+
## References
38+
39+
- [dev-workflow](../dev-workflow/SKILL.md)
40+
- [contentstack-ios-persistence-sdk](../contentstack-ios-persistence-sdk/SKILL.md)

0 commit comments

Comments
 (0)