Skip to content

Commit e1e2d0d

Browse files
Merge pull request #66 from contentstack/development
DX | 15-06-2026 | Release
2 parents f4afec2 + eab34c3 commit e1e2d0d

23 files changed

Lines changed: 1522 additions & 255 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 the repo root **[`AGENTS.md`](../../AGENTS.md)**. All conventions live in **`skills/*/SKILL.md`** (universal for any editor or tool).
4+
5+
This folder only points contributors here so nothing editor-specific duplicates the canonical docs.
Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
name: Back-merge master to development
2+
3+
on:
4+
push:
5+
branches:
6+
- master
7+
workflow_dispatch:
8+
9+
permissions:
10+
contents: read
11+
pull-requests: write
12+
13+
jobs:
14+
open-back-merge-pr:
15+
runs-on: ubuntu-latest
16+
steps:
17+
- name: Checkout
18+
uses: actions/checkout@v4
19+
with:
20+
fetch-depth: 0
21+
22+
- name: Open back-merge PR if needed
23+
env:
24+
GH_TOKEN: ${{ github.token }}
25+
run: |
26+
set -euo pipefail
27+
BASE_BRANCH="development"
28+
SOURCE_BRANCH="master"
29+
30+
git fetch origin "$BASE_BRANCH" "$SOURCE_BRANCH"
31+
32+
if ! git show-ref --verify --quiet "refs/remotes/origin/$BASE_BRANCH"; then
33+
echo "Base branch '$BASE_BRANCH' does not exist on origin; skipping."
34+
exit 0
35+
fi
36+
37+
SOURCE_SHA=$(git rev-parse "origin/$SOURCE_BRANCH")
38+
BASE_SHA=$(git rev-parse "origin/$BASE_BRANCH")
39+
40+
if [ "$SOURCE_SHA" = "$BASE_SHA" ]; then
41+
echo "$SOURCE_BRANCH and $BASE_BRANCH are at the same commit; nothing to back-merge."
42+
exit 0
43+
fi
44+
45+
EXISTING=$(gh pr list --repo "${{ github.repository }}" --base "$BASE_BRANCH" --head "$SOURCE_BRANCH" --state open --json number --jq 'length')
46+
47+
if [ "$EXISTING" -gt 0 ]; then
48+
echo "An open PR from $SOURCE_BRANCH to $BASE_BRANCH already exists; skipping."
49+
exit 0
50+
fi
51+
52+
gh pr create --repo "${{ github.repository }}" --base "$BASE_BRANCH" --head "$SOURCE_BRANCH" --title "chore: back-merge $SOURCE_BRANCH into $BASE_BRANCH" --body "Automated back-merge after changes landed on \\`$SOURCE_BRANCH\\`. Review and merge to keep \\`$BASE_BRANCH\\` in sync."
53+
54+
echo "Created back-merge PR $SOURCE_BRANCH -> $BASE_BRANCH."

.github/workflows/check-branch.yml

Lines changed: 0 additions & 20 deletions
This file was deleted.
Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
name: Check Version Bump
2+
3+
on:
4+
pull_request:
5+
6+
jobs:
7+
version-bump:
8+
name: Version & Changelog bump
9+
runs-on: ubuntu-latest
10+
steps:
11+
- name: Checkout
12+
uses: actions/checkout@v4
13+
with:
14+
fetch-depth: 0
15+
16+
- name: Detect changed files and version bump
17+
id: detect
18+
run: |
19+
if git rev-parse HEAD^2 >/dev/null 2>&1; then
20+
FILES=$(git diff --name-only HEAD^1 HEAD^2)
21+
else
22+
FILES=$(git diff --name-only HEAD~1 HEAD)
23+
fi
24+
VERSION_FILES_CHANGED=false
25+
echo "$FILES" | grep -qx 'package.json' && VERSION_FILES_CHANGED=true
26+
echo "$FILES" | grep -qx 'CHANGELOG.md' && VERSION_FILES_CHANGED=true
27+
echo "version_files_changed=$VERSION_FILES_CHANGED" >> $GITHUB_OUTPUT
28+
# Only lib/, webpack/, dist/, package.json count as release-affecting; .github/ and test/ do not
29+
CODE_CHANGED=false
30+
echo "$FILES" | grep -qE '^lib/|^webpack/|^dist/' && CODE_CHANGED=true
31+
echo "$FILES" | grep -qx 'package.json' && CODE_CHANGED=true
32+
echo "code_changed=$CODE_CHANGED" >> $GITHUB_OUTPUT
33+
34+
- name: Skip when only test/docs/.github changed
35+
if: steps.detect.outputs.code_changed != 'true'
36+
run: |
37+
echo "No release-affecting files changed (e.g. only test/docs/.github). Skipping version-bump check."
38+
exit 0
39+
40+
- name: Fail when version bump was missed
41+
if: steps.detect.outputs.code_changed == 'true' && steps.detect.outputs.version_files_changed != 'true'
42+
run: |
43+
echo "::error::This PR has code changes but no version bump. Please bump the version in package.json and add an entry in CHANGELOG.md."
44+
exit 1
45+
46+
- name: Setup Node
47+
if: steps.detect.outputs.code_changed == 'true' && steps.detect.outputs.version_files_changed == 'true'
48+
uses: actions/setup-node@v4
49+
with:
50+
node-version: '22.x'
51+
52+
- name: Check version bump
53+
if: steps.detect.outputs.code_changed == 'true' && steps.detect.outputs.version_files_changed == 'true'
54+
run: |
55+
set -e
56+
PKG_VERSION=$(node -p "require('./package.json').version.replace(/^v/, '')")
57+
if [ -z "$PKG_VERSION" ]; then
58+
echo "::error::Could not read version from package.json"
59+
exit 1
60+
fi
61+
git fetch --tags --force 2>/dev/null || true
62+
LATEST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || true)
63+
if [ -z "$LATEST_TAG" ]; then
64+
echo "No existing tags found. Skipping version-bump check (first release)."
65+
exit 0
66+
fi
67+
LATEST_VERSION="${LATEST_TAG#v}"
68+
LATEST_VERSION="${LATEST_VERSION%%-*}"
69+
if [ "$(printf '%s\n' "$LATEST_VERSION" "$PKG_VERSION" | sort -V | tail -1)" != "$PKG_VERSION" ]; then
70+
echo "::error::Version bump required: package.json version ($PKG_VERSION) is not greater than latest tag ($LATEST_TAG). Please bump the version in package.json."
71+
exit 1
72+
fi
73+
if [ "$PKG_VERSION" = "$LATEST_VERSION" ]; then
74+
echo "::error::Version bump required: package.json version ($PKG_VERSION) equals latest tag ($LATEST_TAG). Please bump the version in package.json."
75+
exit 1
76+
fi
77+
CHANGELOG_VERSION=$(sed -nE 's/^## \[v?([0-9]+\.[0-9]+\.[0-9]+).*/\1/p' CHANGELOG.md | head -1)
78+
if [ -z "$CHANGELOG_VERSION" ]; then
79+
echo "::error::Could not find a version entry in CHANGELOG.md (expected line like '## [v1.0.0](...)')."
80+
exit 1
81+
fi
82+
if [ "$CHANGELOG_VERSION" != "$PKG_VERSION" ]; then
83+
echo "::error::CHANGELOG version mismatch: CHANGELOG.md top version ($CHANGELOG_VERSION) does not match package.json version ($PKG_VERSION). Please add or update the CHANGELOG entry for $PKG_VERSION."
84+
exit 1
85+
fi
86+
echo "Version bump check passed: package.json and CHANGELOG.md are at $PKG_VERSION (latest tag: $LATEST_TAG)."

.gitignore

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,4 +16,5 @@ tmp/
1616
test/result.json
1717
stdout
1818
build
19-
cache
19+
cache
20+
src/assets/regions.json

AGENTS.md

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# Contentstack PHP SDK – Agent guide
2+
3+
**Universal entry point** for anyone automating or assisting work in this repo—AI agents (Cursor, Copilot, CLI tools), reviewers, and contributors. Conventions and detailed guidance live in **`skills/*/SKILL.md`**, not in editor-specific config, so the same instructions apply whether or not you use Cursor.
4+
5+
## What this repo is
6+
7+
- **Name:** [contentstack-php](https://github.com/contentstack/contentstack-php)
8+
- **Purpose:** PHP library for the Contentstack **Delivery API**—stack initialization, content types, entries, assets, queries, sync, live preview config, and RTE rendering via the optional **`contentstack/utils`** package.
9+
- **Out of scope:** This package is not the Management API client; it focuses on read/delivery patterns documented in the SDK README.
10+
11+
## Tech stack (at a glance)
12+
13+
| Area | Details |
14+
|------|---------|
15+
| Language | PHP (see `composer.json` `require.php`; supports legacy 5.5+ per package) |
16+
| Layout | PSR-4 `Contentstack\``src/`; helper `src/Support/helper.php` |
17+
| Tests | PHPUnit 10 → `test/` (`phpunit.xml`) |
18+
| Docs | Doctum → `composer run generate:docs` (`config.php`) |
19+
| Dependency | `contentstack/utils` for `Utils`, `Option`, RTE rendering helpers |
20+
21+
## Commands (quick reference)
22+
23+
```bash
24+
composer install
25+
composer test
26+
# or: vendor/bin/phpunit
27+
composer run generate:docs
28+
```
29+
30+
Coverage and reports (when configured in `phpunit.xml`) write under `./tmp/`.
31+
32+
## Where the real documentation lives: skills
33+
34+
Read these **`SKILL.md` files** for full conventions—**this is the source of truth** for implementation and review:
35+
36+
| Skill | Path | What it covers |
37+
|-------|------|----------------|
38+
| **Development workflow** | [`skills/dev-workflow/SKILL.md`](skills/dev-workflow/SKILL.md) | Branches, CI expectations, Composer test/docs, PR notes |
39+
| **Contentstack PHP SDK / Utils** | [`skills/contentstack-utils/SKILL.md`](skills/contentstack-utils/SKILL.md) | `Contentstack::Stack`, `Stack`, queries, entries, assets, regions, `contentstack/utils`, semver |
40+
| **PHP style & repo layout** | [`skills/php-style/SKILL.md`](skills/php-style/SKILL.md) | PSR-4, namespaces, docblocks, `src/` layout, PHP version constraints |
41+
| **Testing** | [`skills/testing/SKILL.md`](skills/testing/SKILL.md) | PHPUnit, `test/` layout, constants/helpers, credentials hygiene |
42+
| **Code review** | [`skills/code-review/SKILL.md`](skills/code-review/SKILL.md) | PR checklist (API, errors, deps/SCA, tests), Blocker/Major/Minor |
43+
| **Framework / build** | [`skills/framework/SKILL.md`](skills/framework/SKILL.md) | `composer.json`, autoload, Doctum, optional CI workflows |
44+
45+
An index with short “when to use” hints is in [`skills/README.md`](skills/README.md).
46+
47+
## Using Cursor
48+
49+
If you use **Cursor**, [`.cursor/rules/README.md`](.cursor/rules/README.md) only points to **`AGENTS.md`**—same source of truth as everyone else; no separate `.mdc` rule files.

CHANGELOG.md

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

22
## CHANGELOG
33
------------------------------------------------
4+
## Version 2.5.0
5+
###### Date: 15-June-2026
6+
### Enhancement
7+
- Added support for custom URL endpoint integration
8+
------------------------------------------------
49
## Version 2.4.2
510
###### Date: 05-January-2026
611
### Security fix

composer.json

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,8 +30,11 @@
3030
"code-lts/doctum": "^5.3"
3131
},
3232
"scripts": {
33+
"post-install-cmd": ["@php scripts/download-regions.php"],
34+
"post-update-cmd": ["@php scripts/download-regions.php"],
3335
"generate:docs": "vendor/bin/doctum.php update ./config.php",
34-
"test": "vendor/bin/phpunit"
36+
"test": "vendor/bin/phpunit",
37+
"refresh-regions": "@php scripts/download-regions.php"
3538
},
3639
"require": {
3740
"php" : ">=5.5.0",

0 commit comments

Comments
 (0)