Skip to content

Commit 1503ebe

Browse files
reeshika-hreeshika-h
committed
Add documentation and rules for Contentstack Java CDA SDK
1 parent 9495638 commit 1503ebe

File tree

12 files changed

+489
-0
lines changed

12 files changed

+489
-0
lines changed

‎.cursor/rules/README.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Cursor Rules – Contentstack Java CDA SDK
2+
3+
This directory contains Cursor AI rules that apply when working in this repository. Rules provide persistent context so the AI follows project conventions and Contentstack CDA patterns.
4+
5+
## How rules are applied
6+
7+
- **File-specific rules** use the `globs` frontmatter: they apply when you open or edit files matching that pattern.
8+
- **Always-on rules** use `alwaysApply: true`: they are included in every conversation in this project.
9+
10+
## Rule index
11+
12+
| File | Applies when | Purpose |
13+
|------|--------------|---------|
14+
| **dev-workflow.md** | (Reference only; no glob) | Core development workflow: branches, running tests, PR expectations. Read for process guidance. |
15+
| **java.mdc** | Editing any `**/*.java` file | Java 8 standards: naming, package layout, `com.contentstack.sdk` structure, logging, Lombok/annotations, avoiding raw types. |
16+
| **contentstack-java-cda.mdc** | Editing `src/main/java/com/contentstack/sdk/**/*.java` | CDA-specific patterns: Stack/Config, host/version/region/branch, RetryOptions/RetryInterceptor, callbacks, alignment with Content Delivery API. |
17+
| **testing.mdc** | Editing `src/test/**/*.java` | Testing patterns: JUnit 5, unit vs integration naming (`Test*` vs `*IT`), BaseIntegrationTest, timeouts, JaCoCo. |
18+
| **code-review.mdc** | Always | PR/review checklist: API stability, error handling, backward compatibility, dependencies and security (e.g. SCA). |
19+
20+
## Related
21+
22+
- **AGENTS.md** (repo root) – Main entry point for AI agents: project overview, entry points, and pointers to rules and skills.
23+
- **skills/** – Reusable skill docs (Contentstack Java CDA, testing, code review, framework) for deeper guidance on specific tasks.

‎.cursor/rules/code-review.mdc‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
description: PR and code review checklist – API stability, errors, compatibility, security
3+
alwaysApply: true
4+
---
5+
6+
# Code Review Checklist – Contentstack Java CDA SDK
7+
8+
Use this checklist when reviewing pull requests or before opening a PR.
9+
10+
## API design and stability
11+
12+
- [ ] **Public API:** New or changed public methods/classes are necessary and clearly documented (Javadoc).
13+
- [ ] **Backward compatibility:** No breaking changes to public API unless explicitly called out and justified (e.g. major version).
14+
- [ ] **Naming:** Method and class names are consistent with existing SDK style and CDA terminology.
15+
16+
## Error handling and robustness
17+
18+
- [ ] **Errors:** API failures are mapped to the SDK **`Error`** type and passed through existing callback/result patterns.
19+
- [ ] **Null safety:** No unintended NPEs; parameters and return values are documented or annotated where it matters (e.g. `@NotNull`/`@Nullable`).
20+
- [ ] **Exceptions:** Checked exceptions are handled or declared; unchecked exceptions are used only where appropriate and documented.
21+
22+
## Dependencies and security
23+
24+
- [ ] **Dependencies:** No new dependencies without justification; version bumps are intentional and do not introduce known vulnerabilities.
25+
- [ ] **SCA:** Address any security findings (e.g. from Snyk or similar) in the scope of the PR or in a follow-up.
26+
27+
## Testing
28+
29+
- [ ] **Coverage:** New or modified behavior is covered by unit and/or integration tests as appropriate.
30+
- [ ] **Test quality:** Tests are readable, stable (no flakiness), and follow project conventions (`Test*` / `*IT`, `BaseIntegrationTest` for integration tests).
31+
32+
## Severity (optional)
33+
34+
- **Blocker:** Must fix before merge (e.g. breaking public API without approval, security issue, no tests for new code).
35+
- **Major:** Should fix (e.g. inconsistent error handling, missing Javadoc on new public API).
36+
- **Minor:** Nice to fix (e.g. style, minor docs).

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

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
---
2+
description: Contentstack CDA patterns – Stack/Config, HTTP, retry, callbacks, Content Delivery API
3+
globs: "src/main/java/com/contentstack/sdk/**/*.java"
4+
---
5+
6+
# Contentstack Java 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(apiKey, deliveryToken, environment)` returns a `Stack`. Use `Config` for optional settings.
13+
- **Default host:** `cdn.contentstack.io`; **API version:** `v3` (see `Config`).
14+
- **Config options:** host, version, scheme, region (`ContentstackRegion`), branch, live preview, proxy, connection pool, **RetryOptions**, early access, plugins. 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** go through **`CSHttpConnection`** and **`APIService`** (Retrofit). Do not bypass this 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`).
21+
- **Errors:** Map API errors to the SDK **`Error`** class (errorMessage, errorCode, errDetails) and pass to **`ResultCallBack`** or equivalent callback.
22+
23+
## Retry and resilience
24+
25+
- **RetryOptions:** Configurable retry limit, delay, backoff strategy (e.g. exponential), and retryable status codes (e.g. 408, 429, 502, 503, 504). Defaults are in `RetryOptions`.
26+
- **RetryInterceptor:** Uses `RetryOptions` to retry failed HTTP requests. Keep retry behavior consistent when changing the HTTP client or interceptors.
27+
28+
## Callbacks and async
29+
30+
- Use existing callback types (e.g. **`ResultCallBack`**, **`EntryResultCallBack`**, **`QueryResultsCallBack`**) for async results. Do not introduce incompatible callback signatures without considering backward compatibility.
31+
- Pass **`Error`** and response data through the same callback patterns used elsewhere in the SDK.
32+
33+
## CDA concepts
34+
35+
- **Entry,** **Query,** **Asset,** **Content Type,** **Sync,** **Taxonomy** – follow existing class and method names and the CDA API semantics (e.g. 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 Java CDA SDK
2+
3+
Use this as the standard workflow when contributing to the Java 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+
- **All tests:** `mvn test`
13+
- **Specific test class:** `mvn test -Dtest=TestEntry`
14+
- **Integration tests only:** `mvn test -Dtest='*IT'`
15+
- **Unit tests only:** `mvn test -Dtest='Test*'`
16+
17+
Run tests before opening a PR. Integration tests may require a valid `.env` with stack credentials (see `Credentials` and `BaseIntegrationTest` in the test suite).
18+
19+
## Pull requests
20+
21+
- Ensure the build passes: `mvn clean test`
22+
- Follow the **code-review** rule (see `.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: write a failing test first, then implement to pass, then refactor. 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 8 standards and com.contentstack.sdk conventions for the CDA SDK
3+
globs: "**/*.java"
4+
---
5+
6+
# Java Standards – Contentstack Java CDA SDK
7+
8+
Apply these conventions when editing Java code in this repository.
9+
10+
## Language and runtime
11+
12+
- **Java 8** (source/target 1.8). Do not use language or API features that require a higher version.
13+
- Avoid raw types; use proper generics where applicable.
14+
15+
## Package and layout
16+
17+
- All SDK code lives under **`com.contentstack.sdk`** (see `src/main/java/com/contentstack/sdk/`).
18+
- Keep the existing package structure; do not introduce new top-level packages without alignment with the rest of the SDK.
19+
20+
## Naming
21+
22+
- **Classes:** PascalCase (e.g. `CSHttpConnection`, `RetryOptions`).
23+
- **Methods/variables:** camelCase.
24+
- **Constants:** UPPER_SNAKE_CASE (e.g. in `Constants.java`).
25+
- **Test classes:** `Test*` for unit tests, `*IT` for integration tests (see **testing.mdc** for test rules).
26+
27+
## Logging
28+
29+
- Use **`java.util.logging`** (Logger) as in `CSHttpConnection` and other SDK classes.
30+
- Obtain loggers with `Logger.getLogger(ClassName.class.getName())`.
31+
- Log at appropriate levels (e.g. `warning` for recoverable issues, `fine`/`finer` for debug).
32+
33+
## Annotations and Lombok
34+
35+
- Use **Lombok** where the project already does (e.g. getters/setters, builders) for consistency.
36+
- Use **`@NotNull`** / **`@Nullable`** (e.g. JetBrains annotations) where they are already used to document nullability.
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: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
---
2+
description: JUnit 5 testing patterns, unit vs integration, BaseIntegrationTest, JaCoCo
3+
globs: "src/test/**/*.java"
4+
---
5+
6+
# Testing Rules – Contentstack Java CDA SDK
7+
8+
Apply when writing or editing tests. The project uses **JUnit 5** and **JaCoCo** (see `pom.xml`).
9+
10+
## Test naming and layout
11+
12+
- **Unit tests:** Class name prefix **`Test`** (e.g. `TestEntry`, `TestConfig`). Place in `src/test/java/com/contentstack/sdk/`.
13+
- **Integration tests:** Class name suffix **`IT`** (e.g. `ContentstackIT`, `SyncStackIT`). Same package. Use **`BaseIntegrationTest`** for shared setup and timeouts.
14+
15+
## JUnit 5 usage
16+
17+
- Use **JUnit 5** (Jupiter) APIs: `@Test`, `@BeforeAll`, `@AfterAll`, `@BeforeEach`, `@AfterEach`, `@DisplayName`, etc.
18+
- Prefer **`TestInstance(Lifecycle.PER_CLASS)`** when sharing a single instance across tests (e.g. `BaseIntegrationTest`).
19+
- Use **assertions** from `org.junit.jupiter.api.Assertions`.
20+
21+
## Integration test base and timeouts
22+
23+
- Extend **`BaseIntegrationTest`** for integration tests that need a real stack. It provides:
24+
- `stack` from **`Credentials.getStack()`** (`.env`-based).
25+
- Timeout constants: `DEFAULT_TIMEOUT_SECONDS`, `PERFORMANCE_TIMEOUT_SECONDS`, `LARGE_DATASET_TIMEOUT_SECONDS`.
26+
- Use **`Assertions.assertTimeout(Duration.ofSeconds(...), () -> { ... })`** (or equivalent) for async or long-running operations so tests don’t hang.
27+
28+
## Test data and credentials
29+
30+
- **Credentials:** Use **`Credentials`** and a `.env` file for integration tests (API key, delivery token, environment). Do not commit real tokens; document required env vars (e.g. in README or test docs).
31+
- **Fixtures:** Use existing test assets (e.g. under `src/test/` or `target/test-classes/`) where applicable.
32+
33+
## Coverage
34+
35+
- **JaCoCo** is configured in `pom.xml`. Reports are generated on `mvn test` (e.g. `target/site/jacoco/`). Maintain or improve coverage when adding or changing production code; avoid removing tests that cover critical paths without replacement.

‎AGENTS.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
# Contentstack Java 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 Java CDA SDK (contentstack-java)
8+
- **Purpose:** Java client for the Contentstack **Content Delivery API (CDA)**. It fetches content (entries, assets, content types, sync, taxonomy) from Contentstack and delivers it to Java applications.
9+
- **Repo:** [contentstack-java](https://github.com/contentstack/contentstack-java)
10+
11+
## Tech stack
12+
13+
- **Language:** Java 8 (source/target 1.8)
14+
- **Build:** Maven
15+
- **Testing:** JUnit 5, JaCoCo (coverage)
16+
- **HTTP:** Retrofit 2, OkHttp
17+
- **Other:** Gson, RxJava 3, Lombok, contentstack-utils
18+
19+
## Main entry points
20+
21+
- **`Contentstack`** – Static factory: `Contentstack.stack(apiKey, deliveryToken, environment)` returns a `Stack`.
22+
- **`Stack`** – Main API surface: entries, assets, content types, sync, live preview, etc.
23+
- **`Config`** – Optional configuration: host, version, region, branch, retry, proxy, connection pool, plugins.
24+
- **Paths:** `src/main/java/com/contentstack/sdk/` (production), `src/test/java/com/contentstack/sdk/` (tests).
25+
26+
## Commands
27+
28+
- **Build and test:** `mvn clean test`
29+
- **Single test class:** `mvn test -Dtest=TestEntry`
30+
- **Integration tests only:** `mvn test -Dtest='*IT'`
31+
- **Unit tests only:** `mvn test -Dtest='Test*'`
32+
33+
Integration tests may require a `.env` with stack credentials (see `Credentials` and test README/docs).
34+
35+
## Rules and skills
36+
37+
- **`.cursor/rules/`** – Cursor rules for this repo:
38+
- **README.md** – Index of all rules.
39+
- **dev-workflow.md** – Development workflow (branches, tests, PRs).
40+
- **java.mdc** – Applies to `**/*.java`: Java 8 and SDK conventions.
41+
- **contentstack-java-cda.mdc** – Applies to SDK core: CDA patterns, Config, HTTP, retry, callbacks.
42+
- **testing.mdc** – Applies to `src/test/**/*.java`: JUnit 5, Test* / *IT, BaseIntegrationTest, JaCoCo.
43+
- **code-review.mdc** – Always applied: PR/review checklist.
44+
- **`skills/`** – Reusable skill docs:
45+
- Use **contentstack-java-cda** when implementing or changing CDA API usage or SDK core behavior.
46+
- Use **testing** when adding or refactoring tests.
47+
- Use **code-review** when reviewing PRs or before opening one.
48+
- Use **framework** when changing config, retry, or HTTP layer (Config, RetryOptions, RetryInterceptor, CSHttpConnection).
49+
50+
Refer to `.cursor/rules/README.md` for when each rule applies and to `skills/README.md` for skill 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 Java 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-java-cda** | Implementing or changing CDA features: Stack/Config, entries, assets, content types, sync, taxonomy, HTTP layer, retry, callbacks, error handling. |
10+
| **testing** | Writing or refactoring tests: JUnit 5, unit vs integration layout, BaseIntegrationTest, timeouts, Credentials/.env, 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, retry, or the HTTP layer: Config options, RetryOptions/RetryInterceptor, CSHttpConnection, connection/request flow, error handling. |
13+
14+
## How agents should use skills
15+
16+
- **contentstack-java-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*` / `*IT`), BaseIntegrationTest for integration tests, and existing Surefire/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, RetryOptions, RetryInterceptor, or CSHttpConnection. Keep retry and connection 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 Java CDA SDK
7+
8+
Use this skill when performing or preparing a pull request review for the Java CDA SDK.
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 annotate (e.g. `@NotNull`/`@Nullable`) where it matters for public API.
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 integration tests.
46+
- [ ] **Conventions:** Tests follow naming (`Test*` unit, `*IT` integration) and use `BaseIntegrationTest` for integration tests where 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

0 commit comments

Comments
 (0)