From 78a6bac46b5947403bb2c903b8676f4858160f8e Mon Sep 17 00:00:00 2001 From: reeshika-h Date: Tue, 7 Apr 2026 12:05:12 +0530 Subject: [PATCH 1/2] Add AGENTS.md and related SKILL documentation for Contentstack IOS Persistence --- .cursor/rules/README.md | 5 ++ AGENTS.md | 48 +++++++++++++++++++ skills/README.md | 16 +++++++ skills/code-review/SKILL.md | 40 ++++++++++++++++ .../contentstack-ios-persistence-sdk/SKILL.md | 44 +++++++++++++++++ skills/dev-workflow/SKILL.md | 48 +++++++++++++++++++ skills/ios-persistence-platform/SKILL.md | 45 +++++++++++++++++ skills/objc-swift-ios/SKILL.md | 43 +++++++++++++++++ skills/testing/SKILL.md | 40 ++++++++++++++++ 9 files changed, 329 insertions(+) create mode 100644 .cursor/rules/README.md create mode 100644 AGENTS.md create mode 100644 skills/README.md create mode 100644 skills/code-review/SKILL.md create mode 100644 skills/contentstack-ios-persistence-sdk/SKILL.md create mode 100644 skills/dev-workflow/SKILL.md create mode 100644 skills/ios-persistence-platform/SKILL.md create mode 100644 skills/objc-swift-ios/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..d8f3545 --- /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..37b3591 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,48 @@ +# Contentstack iOS Persistence – Agent guide + +*Universal entry point* for contributors and AI agents. Detailed conventions live in **skills/*/SKILL.md**. + +## What this repo is + +| Field | Detail | +| --- | --- | +| *Name:* | https://github.com/contentstack/contentstack-ios-persistence | +| *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. | +| *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)). | + +## Tech stack (at a glance) + +| Area | Details | +| --- | --- | +| Language | Objective-C (primary); Swift-compatible module imports documented in README. iOS deployment target **12.0** (see podspecs). | +| Build | **Xcode** workspace `ContentstackPersistence.xcworkspace`; **CocoaPods** (`Podfile`, `pod install`). Key sources: `ContentstackPersistence/`, `ContentstackPersistenceCoredata/`, `ContentstackPersistenceRealm/`. Podspecs: `ContentstackPersistence.podspec`, `ContentstackPersistenceCoreData.podspec`, `ContentstackPersistenceRealm.podspec`. | +| Tests | **XCTest** target `ContentstackPersistenceTests`; tests under `ContentstackPersistenceTests/`. | +| Lint / coverage | No SwiftLint / shared coverage config in-repo; follow team standards if added later. | +| Other | Dependencies: **Contentstack** iOS SDK, **Realm** (Realm subspec). Optional persistence: Core Data vs Realm via separate pods. | + +## Commands (quick reference) + +| Command Type | Command | +| --- | --- | +| Build | `pod install` then `xcodebuild -workspace ContentstackPersistence.xcworkspace -scheme ContentstackPersistence -sdk iphonesimulator build` | +| Test | `xcodebuild -workspace ContentstackPersistence.xcworkspace -scheme ContentstackPersistence -destination 'platform=iOS Simulator,name=iPhone 16' test` (adjust simulator name to one installed locally) | +| Lint | *(none configured)* | + +**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`. + +## Where the documentation lives: skills + +| Skill | Path | What it covers | +| --- | --- | --- | +| Dev workflow & CI | [skills/dev-workflow/SKILL.md](skills/dev-workflow/SKILL.md) | Branches, build/test, PR expectations, CI overview | +| SDK & public API | [skills/contentstack-ios-persistence-sdk/SKILL.md](skills/contentstack-ios-persistence-sdk/SKILL.md) | Entry points, pods, sync/persistence boundaries, versioning | +| Objective-C / Swift & layout | [skills/objc-swift-ios/SKILL.md](skills/objc-swift-ios/SKILL.md) | Language conventions and repository layout | +| Testing | [skills/testing/SKILL.md](skills/testing/SKILL.md) | XCTest layout, naming, fixtures, secrets | +| Code review | [skills/code-review/SKILL.md](skills/code-review/SKILL.md) | PR checklist for this repo | +| iOS platform & packaging | [skills/ios-persistence-platform/SKILL.md](skills/ios-persistence-platform/SKILL.md) | CocoaPods, Core Data, Realm, Xcode workspace | + +An index with “when to use” hints is in [skills/README.md](skills/README.md). + +## 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/README.md b/skills/README.md new file mode 100644 index 0000000..4cbabb4 --- /dev/null +++ b/skills/README.md @@ -0,0 +1,16 @@ +# Skills – Contentstack iOS Persistence + +Source of truth for detailed guidance. Read [AGENTS.md](../AGENTS.md) first, then open the skill that matches your task. + +## When to use which skill + +| Skill folder | Use when | +| --- | --- | +| dev-workflow | Branching, PRs to `master`/`next`, CI expectations, local build and test commands | +| contentstack-ios-persistence-sdk | Changing public API, `SyncManager`, stores, podspecs, or integration with Contentstack SDK | +| objc-swift-ios | Objective-C/Swift style, file layout, headers, and module boundaries in this repo | +| testing | Adding or changing XCTest code, test data, or simulator-only concerns | +| code-review | Reviewing or preparing a PR against this repository’s expectations | +| ios-persistence-platform | CocoaPods, Realm vs Core Data, Xcode workspace/schemes, iOS deployment targets | + +Each folder contains `SKILL.md` with YAML frontmatter (`name`, `description`). diff --git a/skills/code-review/SKILL.md b/skills/code-review/SKILL.md new file mode 100644 index 0000000..52b9747 --- /dev/null +++ b/skills/code-review/SKILL.md @@ -0,0 +1,40 @@ +--- +name: code-review +description: PR checklist and severity guidance for contentstack-ios-persistence changes +--- + +# Code review – Contentstack iOS Persistence + +## When to use + +- You are reviewing a PR or preparing one for this repository +- You need a consistent checklist aligned with CI and product boundaries + +## Instructions + +### Before you approve + +- **Branch policy:** Confirm the PR meets `.github/workflows/check-branch.yml` expectations (merges to `master` from `next` where required). +- **Build:** Workspace builds after `pod install`; all three podspec-relevant targets remain consistent if core APIs changed. +- **Tests:** New behavior has XCTest coverage where practical; no committed secrets. +- **Pods:** `Podfile` / `Podfile.lock` changes are intentional; dependency ranges in podspecs match release intent. +- **Docs:** User-visible API or setup changes update [README.md](../../README.md) or product docs links as needed. +- **Security / compliance:** No credentials in code; Talisman-sensitive files respected. + +### Optional severity (for discussion) + +| Level | Examples | +| --- | --- | +| **Blocker** | Breaks consumers’ public API without semver major plan; security issue; build broken | +| **Major** | Missing tests for risky logic; incorrect podspec dependency; sync/data loss risk | +| **Minor** | Style nits, non-user-facing refactors, doc typos | + +### CODEOWNERS + +- Follow [CODEOWNERS](../../CODEOWNERS) for required reviewers. + +## References + +- [dev-workflow](../dev-workflow/SKILL.md) +- [testing](../testing/SKILL.md) +- [contentstack-ios-persistence-sdk](../contentstack-ios-persistence-sdk/SKILL.md) diff --git a/skills/contentstack-ios-persistence-sdk/SKILL.md b/skills/contentstack-ios-persistence-sdk/SKILL.md new file mode 100644 index 0000000..c433540 --- /dev/null +++ b/skills/contentstack-ios-persistence-sdk/SKILL.md @@ -0,0 +1,44 @@ +--- +name: contentstack-ios-persistence-sdk +description: Public API, SyncManager, Core Data and Realm stores, pod boundaries for iOS persistence +--- + +# Contentstack iOS Persistence SDK – Contentstack iOS Persistence + +## When to use + +- You change **`SyncManager`**, **`PersistenceModel`**, **`SyncPersistable`**, **`SyncProtocol`**, or store implementations +- You edit **podspecs** or dependency ranges (`Contentstack`, `Realm`) +- You need to explain how this library relates to the **Contentstack** iOS SDK and sync + +## Instructions + +### What this library owns + +- **Core framework** (`ContentstackPersistence/`): shared types and **`SyncManager`** orchestration; depends on **Contentstack** for stack/sync, not on Realm/Core Data directly in the base podspec. +- **Core Data path** (`ContentstackPersistenceCoredata/` + `ContentstackPersistenceCoreData.podspec`): **`CoreDataStore`** and Core Data–backed persistence. +- **Realm path** (`ContentstackPersistenceRealm/` + `ContentstackPersistenceRealm.podspec`): **`RealmStore`** and Realm-backed persistence; adds an explicit **Realm** dependency range in the podspec. + +### Public surface + +- Umbrella / public headers are declared per podspec (`s.public_header_files`); keep Objective-C headers stable for binary compatibility expectations in downstream apps. +- **`SyncManager`** is the main integration point: constructed with a **Stack** (from Contentstack SDK) and a store conforming to the persistence abstraction (`CoreDataStore`, `RealmStore`, etc.). +- **`PersistenceModel`** maps sync stack, assets, and entry types when customizing what gets persisted. + +### Boundaries + +- **In scope:** Local persistence adapters, sync callback handling, model mapping for offline storage. +- **Out of scope:** Implementing REST/CDA calls here—that lives in **Contentstack**; this repo consumes **Stack** and sync flows from that SDK. + +### Versioning + +- Bump **`s.version`** consistently across podspecs when releasing; **`s.source`** `:tag` should match your git tagging convention (e.g. `v0.1.1`). +- Subspecs depend on **`ContentstackPersistence`** with a matching semver range—keep those constraints coherent when you change the core. + +## References + +- [README.md](../../README.md) — integration examples (Objective-C and Swift) +- [objc-swift-ios](../objc-swift-ios/SKILL.md) +- [ios-persistence-platform](../ios-persistence-platform/SKILL.md) +- [Contentstack iOS Persistence docs](https://www.contentstack.com/docs/guide/synchronization/using-realm-persistence-library-with-ios-sync-sdk) +- [Content Delivery API](https://www.contentstack.com/docs/apis/content-delivery-api/) diff --git a/skills/dev-workflow/SKILL.md b/skills/dev-workflow/SKILL.md new file mode 100644 index 0000000..443e1c1 --- /dev/null +++ b/skills/dev-workflow/SKILL.md @@ -0,0 +1,48 @@ +--- +name: dev-workflow +description: Branch policy, CI, and local build/test commands for contentstack-ios-persistence +--- + +# Dev workflow – Contentstack iOS Persistence + +## When to use + +- You are opening a PR, choosing a base branch, or interpreting CI failures +- You need the canonical `pod install` / `xcodebuild` commands for this repo +- You want release or versioning expectations (podspecs, tags) + +## Instructions + +### Branches and PRs + +- **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. +- Use **CODEOWNERS** for required reviewers when present. + +### Local development + +1. Install pods: `pod install` from the repo root (generates/updates `Pods/` and integrates with the workspace). +2. Open **`ContentstackPersistence.xcworkspace`** (not the `.xcodeproj` alone) when working with CocoaPods. + +### Build and test + +- **Build:** `xcodebuild -workspace ContentstackPersistence.xcworkspace -scheme ContentstackPersistence -sdk iphonesimulator build` +- **Test:** `xcodebuild -workspace ContentstackPersistence.xcworkspace -scheme ContentstackPersistence -destination 'platform=iOS Simulator,name=iPhone 16' test` — pick a simulator that exists on your Mac. + +### CI (GitHub Actions) + +- **Branch check:** `.github/workflows/check-branch.yml` — PRs to `master` from branches other than `next` fail by policy. +- **SCA:** `.github/workflows/sca-scan.yml` — Snyk `snyk test` on PRs (requires `SNYK_TOKEN` in org secrets). +- **Policy:** `.github/workflows/policy-scan.yml` — public repos: `SECURITY.md` and license file with current year. +- **Issues:** `.github/workflows/issues-jira.yml` — Jira integration for issues. + +### Versioning and release hints + +- 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). +- **Talisman:** `.talismanrc` may apply to pre-commit secret scanning; do not commit API keys or tokens. + +## References + +- [AGENTS.md](../../AGENTS.md) +- [contentstack-ios-persistence-sdk](../contentstack-ios-persistence-sdk/SKILL.md) +- [testing](../testing/SKILL.md) +- [ios-persistence-platform](../ios-persistence-platform/SKILL.md) diff --git a/skills/ios-persistence-platform/SKILL.md b/skills/ios-persistence-platform/SKILL.md new file mode 100644 index 0000000..a110490 --- /dev/null +++ b/skills/ios-persistence-platform/SKILL.md @@ -0,0 +1,45 @@ +--- +name: ios-persistence-platform +description: CocoaPods, Xcode workspace, Realm vs Core Data, and iOS deployment for this repo +--- + +# iOS persistence platform – Contentstack iOS Persistence + +## When to use + +- You change **CocoaPods** integration (`Podfile`, `Podfile.lock`, podspecs) +- You choose or explain **Realm** vs **Core Data** delivery paths +- You adjust **iOS deployment target** or linker settings (`OTHER_LDFLAGS`, etc.) + +## Instructions + +### CocoaPods + +- **Install:** `pod install` from repo root; open **`ContentstackPersistence.xcworkspace`**. +- **Consumable pods:** `ContentstackPersistence` (core), `ContentstackPersistenceCoreData`, `ContentstackPersistenceRealm` — see [README.md](../../README.md) for `Podfile` lines. +- **Lockfile:** Commit `Podfile.lock` when dependency resolution should be reproducible for CI or the team (follow existing repo practice). + +### Realm vs Core Data + +- **Realm:** `ContentstackPersistenceRealm` pod; depends on **Realm** (see `ContentstackPersistenceRealm.podspec`); implementation in `ContentstackPersistenceRealm/`. +- **Core Data:** `ContentstackPersistenceCoreData` pod; no Realm dependency; implementation in `ContentstackPersistenceCoredata/`. +- **Core** pod `ContentstackPersistence` is shared; apps pick one persistence backend or structure their app module graph accordingly. + +### Xcode + +- **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). +- **SDK:** `iphonesimulator` for typical local builds; device builds when validating arm64/device-only issues. + +### Deployment target + +- Podspecs specify **`s.ios.deployment_target = '12.0'`** — keep podspecs aligned when raising the minimum iOS version. + +### Contentstack SDK + +- 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). + +## References + +- [contentstack-ios-persistence-sdk](../contentstack-ios-persistence-sdk/SKILL.md) +- [dev-workflow](../dev-workflow/SKILL.md) +- [Example app (external)](https://github.com/contentstack/contentstack-ios-persistence-example) diff --git a/skills/objc-swift-ios/SKILL.md b/skills/objc-swift-ios/SKILL.md new file mode 100644 index 0000000..12cde55 --- /dev/null +++ b/skills/objc-swift-ios/SKILL.md @@ -0,0 +1,43 @@ +--- +name: objc-swift-ios +description: Objective-C-first layout, headers, and Swift interop for this iOS persistence repo +--- + +# Objective-C / Swift & repo layout – Contentstack iOS Persistence + +## When to use + +- You add or rename `.h` / `.m` files under `ContentstackPersistence/`, `ContentstackPersistenceCoredata/`, or `ContentstackPersistenceRealm/` +- You expose symbols to Swift consumers (`@import` / `import` patterns in README) +- You align with existing naming and module structure + +## Instructions + +### Language + +- **Primary implementation language:** Objective-C (`.m` / `.h`). +- **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). + +### Layout (by folder) + +| Path | Role | +| --- | --- | +| `ContentstackPersistence/` | Core framework: `SyncManager`, `PersistenceModel`, protocols, umbrella `ContentstackPersistence.h` | +| `ContentstackPersistenceCoredata/` | Core Data store implementation | +| `ContentstackPersistenceRealm/` | Realm store implementation | +| `ContentstackPersistenceTests/` | XCTest sources | + +### Headers and modules + +- Public API is driven by **`s.public_header_files`** in each podspec—new public headers must be listed there. +- Keep umbrella / main header includes predictable; consumers may use `#import ` or `@import Module`. + +### Naming and style + +- Match existing patterns: Objective-C naming, file names aligned with class names (e.g. `SyncManager.h` / `SyncManager.m`). +- Avoid drive-by reformatting unrelated code in the same change as feature work. + +## References + +- [contentstack-ios-persistence-sdk](../contentstack-ios-persistence-sdk/SKILL.md) +- [testing](../testing/SKILL.md) diff --git a/skills/testing/SKILL.md b/skills/testing/SKILL.md new file mode 100644 index 0000000..2e35b78 --- /dev/null +++ b/skills/testing/SKILL.md @@ -0,0 +1,40 @@ +--- +name: testing +description: XCTest layout, simulator runs, and secrets policy for ContentstackPersistenceTests +--- + +# Testing – Contentstack iOS Persistence + +## When to use + +- You add or change tests under `ContentstackPersistenceTests/` +- You run tests locally or debug CI test failures +- You need guidance on credentials and fixtures + +## Instructions + +### Runner and location + +- **Framework:** XCTest (`ContentstackPersistenceTests.m` and future `*Tests.m` files). +- **Target:** `ContentstackPersistenceTests` (xctest bundle `ContentstackPersistenceTests.xctest`). +- **Run:** After `pod install`, use `xcodebuild` with scheme `ContentstackPersistence` and action `test`, with an iOS Simulator destination (see [AGENTS.md](../../AGENTS.md)). + +### Naming and structure + +- Test class inherits from `XCTestCase`; methods follow `- (void)test*` naming. +- Prefer descriptive test names that state what is being verified (replace placeholder `testExample` when adding real coverage). + +### Credentials and data + +- **Do not** commit API keys, delivery tokens, or stack secrets to tests or repo files. +- Prefer mocks, dependency injection at the store/sync boundaries, or local fixtures checked in without secrets. +- 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. + +### Coverage + +- 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). + +## References + +- [dev-workflow](../dev-workflow/SKILL.md) +- [contentstack-ios-persistence-sdk](../contentstack-ios-persistence-sdk/SKILL.md) From 0c36e132242f85fd9540adea17b0c2246609e7a5 Mon Sep 17 00:00:00 2001 From: reeshika-h Date: Tue, 7 Apr 2026 12:09:54 +0530 Subject: [PATCH 2/2] license update --- LICENSE | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/LICENSE b/LICENSE index d2d6d27..bcbfb04 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ MIT License -Copyright (c) 2012-2023 Contentstack (http://app.contentstack.com) +Copyright (c) 2012-2026 Contentstack (http://app.contentstack.com) Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal