Skip to content

Commit 4640e42

Browse files
naman-contentstacknaman-contentstack
authored
Merge pull request #62 from contentstack/development
DX | 20-04-2026 | Release dev -> stg
2 parents de0666a + d46ff17 commit 4640e42

12 files changed

Lines changed: 338 additions & 0 deletions

File tree

‎.cursor/rules/README.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
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.
6+
7+
Path to AGENTS.md: from `.cursor/rules/README.md` use `../../AGENTS.md`.

‎AGENTS.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
# Contentstack Dart SDK – 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-dart](https://github.com/contentstack/contentstack-dart) |
10+
| *Purpose:* | Official Dart package for Contentstack’s **Content Delivery API (CDA)**—fetch and query published content (entries, assets, content types), live preview, sync, and image transforms. |
11+
| *Out of scope (if any):* | Not the Management API, not a Flutter UI kit, and not a standalone HTTP server—this is a client library built on the `http` package. |
12+
13+
## Tech stack (at a glance)
14+
15+
| Area | Details |
16+
| --- | --- |
17+
| Language | Dart SDK `>=2.12.0 <4.0.0` (`environment` in `pubspec.yaml`) |
18+
| Build | `dart pub get`; JSON models use `json_serializable`—regenerate with `dart run build_runner build --delete-conflicting-outputs` when `*.dart` parts change (`pubspec.yaml`, `analysis_options.yaml` excludes `*.g.dart`) |
19+
| Tests | `package:test`; tests under `test/*.dart` (see `test/run_test.sh` for optional coverage steps) |
20+
| Lint / coverage | Analyzer + linter rules in `analysis_options.yaml` (`flutter_lints`-aligned custom rule set); coverage via `dart test --coverage=./coverage` and tooling described in `test/run_test.sh` |
21+
| Other | Runtime deps: `http`, `json_annotation`, `logger`, `path`, `dotenv`, `file`; API docs generated with `dartdoc` (dev dependency) |
22+
23+
## Commands (quick reference)
24+
25+
| Command Type | Command |
26+
| --- | --- |
27+
| Build | `dart pub get` |
28+
| Codegen (when models / `part` files change) | `dart run build_runner build --delete-conflicting-outputs` |
29+
| Test | `dart test` |
30+
| Lint | `dart analyze` |
31+
| Format (optional) | `dart format .` |
32+
33+
**CI / automation:** workflows under [.github/workflows/](.github/workflows/) (e.g. branch checks, publish to pub.dev on version tags, policy scan, Jira integration).
34+
35+
## Where the documentation lives: skills
36+
37+
| Skill | Path | What it covers |
38+
| --- | --- | --- |
39+
| Dev workflow | [skills/dev-workflow/SKILL.md](skills/dev-workflow/SKILL.md) | Branches, PR expectations, local commands, optional codegen |
40+
| Contentstack Dart SDK (API) | [skills/contentstack-dart-sdk/SKILL.md](skills/contentstack-dart-sdk/SKILL.md) | Public surface, `Stack`/queries, errors, integration boundaries |
41+
| Dart style & layout | [skills/dart-style/SKILL.md](skills/dart-style/SKILL.md) | Package layout, imports, analyzer conventions |
42+
| Testing | [skills/testing/SKILL.md](skills/testing/SKILL.md) | Test layout, env/credentials, coverage notes |
43+
| Code review | [skills/code-review/SKILL.md](skills/code-review/SKILL.md) | PR checklist and severity hints |
44+
| Runtime & HTTP | [skills/runtime-and-http/SKILL.md](skills/runtime-and-http/SKILL.md) | HTTP client usage, env config, logging, packaging |
45+
46+
An index with “when to use” hints is in [skills/README.md](skills/README.md).
47+
48+
## Using Cursor (optional)
49+
50+
If you use *Cursor*, [.cursor/rules/README.md](.cursor/rules/README.md) only points to *AGENTS.md*—same docs as everyone else.

‎CHANGELOG.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,11 @@
11
# CHANGELOG
22

3+
### **APR-09-2026**
4+
5+
#### Documentation
6+
7+
- Add deprecation notice and migration guidance to the Content Delivery API. See [DEPRECATION.md](DEPRECATION.md).
8+
39
### **JAN-12-2026**
410

511
#### v1.0.2 - Improved Error messages

‎DEPRECATION.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# Deprecation notice: Contentstack Dart SDK (pub.dev)
2+
3+
This page is for **developers using the Contentstack Dart SDK** published on **pub.dev** as [`contentstack`](https://pub.dev/packages/contentstack).
4+
5+
## What this means for you
6+
7+
**We are deprecating this SDK as the recommended path for new Dart and Flutter work.** If you are **starting a new project**, use our **[Content Delivery API (CDA)](https://www.contentstack.com/docs/developers/apis/content-delivery-api/)** directly with your preferred HTTP client (for example `package:http` or your app’s existing networking stack).
8+
9+
**If you already ship an app** that depends on `contentstack`, you can **keep using it**. Your integration continues to work. Plan a move to direct CDA usage when it fits your release schedule—you do not have to change immediately.
10+
11+
## What to use for new projects
12+
13+
| | Link |
14+
|---|------|
15+
| **Content Delivery API** | [Content Delivery API documentation](https://www.contentstack.com/docs/developers/apis/content-delivery-api/) |
16+
17+
## Why we are making this change
18+
19+
We are focusing investment on **direct API usage** and **documented integration patterns** for Dart and Flutter. This repository will remain in **maintenance**: we may address critical or security issues where we can, but **we do not plan new features** in the Dart SDK.
20+
21+
## Support for this SDK going forward
22+
23+
This repository will stay in **maintenance** as described above. Feature work and new capabilities should be built against the **Content Delivery API** and your application code.
24+
25+
If you need help choosing a migration path or timing, contact **[Contentstack support](https://www.contentstack.com/)** or your account team.

‎README.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,11 @@
11
# ![Contentstack](https://www.contentstack.com/docs/static/images/contentstack.png)
22

3+
## Important: Dart SDK and pub.dev
4+
5+
**We are deprecating** the **Contentstack** Dart SDK on pub.dev as the supported path for **new** development. **New Dart or Flutter projects should use the [Content Delivery API](https://www.contentstack.com/docs/developers/apis/content-delivery-api/)** directly with the HTTP client of your choice.
6+
7+
**Already using this SDK?** You can keep shipping with your current dependencies and migrate when it makes sense for your app. More detail: **[DEPRECATION.md](DEPRECATION.md)**.
8+
39
## Dart SDK for Contentstack
410

511
![version](https://img.shields.io/github/v/release/contentstack/contentstack-dart)

‎skills/README.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# Skills – Contentstack Dart SDK
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](dev-workflow/) | Branching, CI expectations, day-to-day build/test/lint/codegen |
10+
| [contentstack-dart-sdk](contentstack-dart-sdk/) | Changing public API, `Stack`, queries, errors, or CDA behavior |
11+
| [dart-style](dart-style/) | Imports, library structure, analyzer/linter alignment |
12+
| [testing](testing/) | Writing or running tests, fixtures, coverage, credentials |
13+
| [code-review](code-review/) | Preparing or reviewing a PR |
14+
| [runtime-and-http](runtime-and-http/) | HTTP usage, retries/env, dependencies, or packaging concerns |
15+
16+
Each folder contains `SKILL.md` with YAML frontmatter (`name`, `description`).

‎skills/code-review/SKILL.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
name: code-review
3+
description: Use when preparing a pull request or reviewing changes for this SDK repository.
4+
---
5+
# Code review – Contentstack Dart SDK
6+
7+
## When to use
8+
9+
- Before requesting review or approving a PR
10+
- When triaging risk (API breaks, security, test gaps)
11+
12+
## Instructions
13+
14+
### Checklist
15+
16+
- **Behavior:** Change matches CDA semantics; no accidental Management API assumptions
17+
- **API:** Public exports updated deliberately in `lib/contentstack.dart`; breaking changes documented and versioned
18+
- **Quality:** `dart analyze` clean; `dart test` passes; codegen committed if `*.g.dart` changed
19+
- **Security:** No API keys, tokens, or `.env` with secrets in the diff
20+
- **Style:** Matches `analysis_options.yaml` and project patterns ([../dart-style/SKILL.md](../dart-style/SKILL.md))
21+
22+
### Severity (optional)
23+
24+
- **Blocker:** Breaks consumers, leaks credentials, or ships broken analyze/tests
25+
- **Major:** Incorrect API usage, missing tests for risky logic, undocumented breaking change
26+
- **Minor:** Naming, small refactors, doc nits
27+
28+
### Process
29+
30+
- Respect branch rules in [.github/workflows/check-branch.yml](../../.github/workflows/check-branch.yml) for target branches
31+
32+
## References
33+
34+
- [../dev-workflow/SKILL.md](../dev-workflow/SKILL.md)
35+
- [../testing/SKILL.md](../testing/SKILL.md)
36+
- [AGENTS.md](../../AGENTS.md)

‎skills/contentstack-dart-sdk/SKILL.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
---
2+
name: contentstack-dart-sdk
3+
description: Use when changing the public API, Stack, queries, CDA calls, errors, or SDK boundaries.
4+
---
5+
# Contentstack Dart SDK (API) – Contentstack Dart SDK
6+
7+
## When to use
8+
9+
- Adding or changing exported types in `lib/contentstack.dart`
10+
- Working on `Stack`, content types, entries, queries, assets, image transforms, sync, or live preview
11+
- Defining or handling SDK errors and response models
12+
13+
## Instructions
14+
15+
### Entry points
16+
17+
- Main library: [`lib/contentstack.dart`](../../lib/contentstack.dart) re-exports `src/` modules—prefer exporting new public types from there
18+
- Core client: [`lib/src/stack.dart`](../../lib/src/stack.dart) and related `entry.dart`, `query.dart`, `contenttype.dart`, `asset.dart`, `image_transform.dart`
19+
20+
### API boundaries
21+
22+
- This package targets **Content Delivery API** usage (read/query published content), not Management API operations
23+
- HTTP is performed via the `http` package; see [../runtime-and-http/SKILL.md](../runtime-and-http/SKILL.md)
24+
25+
### Models and errors
26+
27+
- JSON models use `json_annotation` + generated `*.g.dart` parts—regenerate after schema changes (see [../dev-workflow/SKILL.md](../dev-workflow/SKILL.md))
28+
- Errors live under [`lib/src/error/`](../../lib/src/error/); keep messages and types consistent with CDA behavior
29+
30+
### Versioning
31+
32+
- Package version and changelog: follow semver in `pubspec.yaml` and `CHANGELOG.md` when releasing
33+
34+
## References
35+
36+
- [Content Delivery API](https://www.contentstack.com/docs/developers/apis/content-delivery-api/)
37+
- [../dart-style/SKILL.md](../dart-style/SKILL.md) — imports and docs
38+
- [../testing/SKILL.md](../testing/SKILL.md) — integration-style tests

‎skills/dart-style/SKILL.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
---
2+
name: dart-style
3+
description: Use for package layout, imports, naming, and analyzer/linter alignment in this Dart repo.
4+
---
5+
# Dart style & layout – Contentstack Dart SDK
6+
7+
## When to use
8+
9+
- Adding new files under `lib/` or `test/`
10+
- Fixing analyzer or lint findings
11+
- Choosing import style (`package:` vs relative) consistent with this repo
12+
13+
## Instructions
14+
15+
### Layout
16+
17+
- Public API: `lib/contentstack.dart` and `lib/src/`
18+
- Tests: `test/*.dart` alongside optional scripts like `test/run_test.sh`
19+
- Analyzer config: root [`analysis_options.yaml`](../../analysis_options.yaml)
20+
21+
### Conventions reflected in `analysis_options.yaml`
22+
23+
- Prefer `package:` imports for public code; `avoid_relative_lib_imports` is enabled
24+
- `directives_ordering`, `package_api_docs` (document public APIs), `always_declare_return_types`, strong null-safety practices
25+
- Generated `*.g.dart` files are excluded from analysis—do not hand-edit them
26+
27+
### Naming
28+
29+
- Follow `file_names`, `camel_case_types`, `non_constant_identifier_names` as enforced by the configured lints
30+
31+
## References
32+
33+
- [../dev-workflow/SKILL.md](../dev-workflow/SKILL.md) — `dart analyze` / format
34+
- [Effective Dart](https://dart.dev/effective-dart)
35+
- [Analyzer options](https://dart.dev/tools/analysis)

‎skills/dev-workflow/SKILL.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
---
2+
name: dev-workflow
3+
description: Use for branches, CI, local build/test/lint, codegen, and PR workflow for this repo.
4+
---
5+
# Dev workflow – Contentstack Dart SDK
6+
7+
## When to use
8+
9+
- Starting work in this repository or onboarding
10+
- Before opening a PR (verify analyze, tests, format)
11+
- After editing JSON-serializable models or `part` files
12+
13+
## Instructions
14+
15+
### Dependencies and codegen
16+
17+
- Install deps: `dart pub get`
18+
- If you change files that use `json_serializable` / `part '*.g.dart'`, run:
19+
`dart run build_runner build --delete-conflicting-outputs`
20+
Generated files are excluded from manual lint in `analysis_options.yaml`
21+
22+
### Quality gates
23+
24+
- Static analysis: `dart analyze` (rules in `analysis_options.yaml`)
25+
- Tests: `dart test`
26+
- Optional format check: `dart format .`
27+
28+
### Branches and automation
29+
30+
- Pull requests run [.github/workflows/check-branch.yml](../../.github/workflows/check-branch.yml) (e.g. restrictions when targeting `master`)
31+
- Publishing: [.github/workflows/publish.yml](../../.github/workflows/publish.yml) on semver tags; dry-run uses `dart pub publish --dry-run`
32+
33+
### Package docs
34+
35+
- HTML API docs: `dartdoc` is listed in `pubspec.yaml`; generate when documenting public API changes
36+
37+
## References
38+
39+
- [../contentstack-dart-sdk/SKILL.md](../contentstack-dart-sdk/SKILL.md) — API surface
40+
- [../testing/SKILL.md](../testing/SKILL.md) — tests and coverage
41+
- [../dart-style/SKILL.md](../dart-style/SKILL.md) — layout and analyzer
42+
- [Dart SDK environment](https://dart.dev/tools/pub/pubspec#sdk)

0 commit comments

Comments
 (0)