[Chore] Better changesets release flow

.changeset/README.md

@@ -0,0 +1,10 @@
+# Changesets
+
+Changesets allows flexible management of multiple packages in a monorepo
+
+[Changeset docs](https://github.com/changesets/changesets)
+[Common questions](https://github.com/changesets/changesets/blob/main/docs/common-questions.md)
+
+Quick references:
+- `yarn changeset` add a changeset for current changes.
+- `yarn changeset:cascade-version` - apply version changes from current changesets onto the monrepo (usually runs via CI)

.changeset/config.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@3.1.2/schema.json",
+  "changelog": "../scripts/changesets/changelog.ts",
+  "commit": false,
+  "access": "public",
+  "baseBranch": "dev",
+  "ignore": [],
+  "snapshot": {
+    "useCalculatedVersion": true,
+    "prereleaseTemplate": "{tag}.{datetime}"
+  }
+}

.github/workflows/hotfix_release_prep.yml

@@ -0,0 +1,104 @@
+name: Prepare Hotfix Release
+
+permissions:
+  contents: write
+
+on:
+  workflow_dispatch:
+    inputs:
+      package_name:
+        description: 'Full package name'
+        required: true
+        type: choice
+        options:
+          - '@sitecore-content-sdk/nextjs'
+          - '@sitecore-content-sdk/cli'
+          - '@sitecore-content-sdk/react'
+          - '@sitecore-content-sdk/search'
+          - 'create-content-sdk'
+          - '@sitecore-content-sdk/core'
+          - '@sitecore-content-sdk/content'
+          - '@sitecore-content-sdk/analytics-core'
+          - '@sitecore-content-sdk/events'
+          - '@sitecore-content-sdk/personalize'
+
+      version:
+        description: 'Base version to hotfix'
+        required: true
+        type: string
+
+jobs:
+  prep-release:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Generate GitHub App Token
+        id: generate-token
+        uses: actions/create-github-app-token@v2
+        with:
+          app-id: ${{ secrets.GH_APP_ID }}
+          private-key: ${{ secrets.GH_APP_PRIVATE_KEY }}
+          owner: ${{ github.repository_owner }}
+
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+          token: ${{ steps.generate-token.outputs.token }}
+
+      - name: Set git configuration
+        run: |
+          git config --global user.email builds@sitecore.com
+          git config --global user.name "content-sdk-bot"
+          git remote set-url origin https://x-access-token:${{ steps.generate-token.outputs.token }}@github.com/${{ github.repository }}
+
+      - name: Use Node.js 24
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+
+      - name: Setup GH action
+        id: setup-gh-action
+        run: |
+          BASE_RELEASE="${{ inputs.package_name }}@${{ inputs.version }}"
+
+          if ! git rev-parse "refs/tags/$BASE_RELEASE" >/dev/null 2>&1; then
+            echo "Release tag $BASE_RELEASE not found. Please validate your inputs."
+            exit 1
+          fi
+
+          echo "base_release=$BASE_RELEASE" >> $GITHUB_OUTPUT
+
+      - name: Create release branch
+        id: create-branch
+        run: |
+          BRANCH_NAME="release/${{ steps.setup-gh-action.outputs.base_release }}-hotfix"
+
+          if git ls-remote --heads origin "$BRANCH_NAME" | grep -q .; then
+            echo "Hotfix branch $BRANCH_NAME already exists"
+            echo "Please check if this is expected. Delete the branch and run action again if not."
+            exit 1
+          else
+            git checkout -b "$BRANCH_NAME" "${{ steps.setup-gh-action.outputs.base_release }}"
+            git push -u origin "$BRANCH_NAME"
+            echo "Branch $BRANCH_NAME created and pushed"
+          fi
+
+      - name: Summary
+        run: |
+          BRANCH_NAME="${{ steps.create-branch.outputs.branch_name }}"
+          BASE_RELEASE="${{ steps.setup-gh-action.outputs.base_release }}"
+
+          echo "## Release Branch Prepared" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "| Property | Value |" >> $GITHUB_STEP_SUMMARY
+          echo "|----------|-------|" >> $GITHUB_STEP_SUMMARY
+          echo "| **Target Package** | \`$BASE_RELEASE\` |" >> $GITHUB_STEP_SUMMARY
+          echo "| **Release Branch** | \`$BRANCH_NAME\` |" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "### Next Steps:" >> $GITHUB_STEP_SUMMARY
+          echo "1. Checkout the branch: \`git checkout $BRANCH_NAME\`" >> $GITHUB_STEP_SUMMARY
+          echo "2. Cherrypick or add patch changes" >> $GITHUB_STEP_SUMMARY
+          echo "3. Add changesets (\`yarn changeset\`)" >> $GITHUB_STEP_SUMMARY
+          echo "4. Prepare PR(s) with hotfix changes" >> $GITHUB_STEP_SUMMARY
+          echo "5. Push changes. This will update pre-patch canaries and automatically create the hotfix release PR" >> $GITHUB_STEP_SUMMARY
+          echo "6. Merge hotfix release PR to trigger the release" >> $GITHUB_STEP_SUMMARY

.github/workflows/publish.yml

@@ -1,70 +1,182 @@
-name: Publish
-
-on:
-  push:
-    branches:
-      - dev
-      - 'release/**'
-    paths:
-      - '**'
-
-jobs:
-  publish:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-    env:
-      YARN_ENABLE_IMMUTABLE_INSTALLS: false
-    steps:
-      - name: Generate GitHub App Token
-        id: generate-token
-        uses: actions/create-github-app-token@v2
-        with:
-          app-id: ${{ secrets.GH_APP_ID }}
-          private-key: ${{ secrets.GH_APP_PRIVATE_KEY }}
-          owner: ${{ github.repository_owner }}
-
-      - uses: actions/checkout@v4
-        with:
-          ref: ${{ github.ref }}
-          fetch-depth: 0
-          persist-credentials: false
-          token: ${{ steps.generate-token.outputs.token }}
-
-      - name: Set git configuration
-        run: |
-          git config --global user.email builds@sitecore.com
-          git config --global user.name "content-sdk-bot"
-          git remote set-url origin https://x-access-token:${{ steps.generate-token.outputs.token }}@github.com/${{ github.repository }}
-
-      - name: Use Node.js 24
-        uses: actions/setup-node@v4
-        with:
-          node-version: 24
-
-      - name: Install dependencies
-        run: |
-          yarn cache clean --all
-          yarn install --immutable
-
-      - name: Build packages
-        run: npm run build
-
-      - name: Generate API docs
-        run: |
-          yarn generate-docs
-          git add ./ref-docs/**/*
-          git commit -m "Update API docs"
-
-      - name: Pre-release version update
-        run: |
-          npx lerna version prerelease --exact --preid canary --force-publish --message "%s [skip ci]" --yes
-        env:
-          GH_TOKEN: ${{ steps.generate-token.outputs.token }}
-
-      - name: Pre-release canary publish
-        run: |
-          echo //registry.npmjs.org/:_authToken=${NPM_TOKEN} > .npmrc
-          npx lerna publish from-git --exact --canary --pre-dist-tag canary --preid canary --no-verify-access --yes
-        env:
-          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+name: Publish
+
+permissions:
+  contents: read
+  pull-requests: write
+
+on:
+  # Trigger for canary and stable releases:
+  # - Stable prod release: When PR from changeset-release/* branch is merged with [release] prefix
+  # - Canary release: Push to dev or release/* branches (not from changeset-release merge)
+  push:
+    branches:
+      - dev
+      - 'release/**'
+    paths:
+      - '**'
+
+# changesets/action runs csdk:prep-release which consumes .changeset/*.md in that runner.
+# Canary snapshot must run in a separate job with its own checkout so changesets still exist.
+jobs:
+  stable-release-pre:
+    runs-on: ubuntu-latest
+    env:
+      YARN_ENABLE_IMMUTABLE_INSTALLS: false
+    steps:
+      - name: Generate GitHub App Token
+        id: generate-token
+        uses: actions/create-github-app-token@v2
+        with:
+          app-id: ${{ secrets.GH_APP_ID }}
+          private-key: ${{ secrets.GH_APP_PRIVATE_KEY }}
+          owner: ${{ github.repository_owner }}
+
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.ref }}
+          fetch-depth: 0
+          persist-credentials: false
+          token: ${{ steps.generate-token.outputs.token }}
+
+      - name: Set git configuration
+        run: |
+          git config --global user.email builds@sitecore.com
+          git config --global user.name "content-sdk-bot"
+          git remote set-url origin https://x-access-token:${{ steps.generate-token.outputs.token }}@github.com/${{ github.repository }}
+
+      - name: Use Node.js 24
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+
+      - name: Install dependencies
+        run: |
+          yarn cache clean --all
+          yarn install --immutable
+
+      - name: Build packages
+        run: npm run build
+
+      - name: Generate API docs
+        run: |
+          yarn generate-docs
+          if [ -n "$(git status --porcelain)" ]; then
+            git add ./ref-docs/**/*
+            git commit -m "Update API docs [skip ci]" || echo "⚠️ Failed to commit API docs (may already be committed)"
+            git push origin HEAD:${{ github.ref_name }} || echo "⚠️ Failed to push API docs (may already be pushed or no changes)"
+          else
+            echo "No API doc changes to commit"
+          fi
+
+      - name: Creating .npmrc
+        run: |
+          NPM_REGISTRY="${NPM_REGISTRY%/}"
+          NPM_REGISTRY="${NPM_REGISTRY}/"
+          write_npmrc() {
+            {
+              echo "@sitecore-content-sdk:registry=https://$NPM_REGISTRY"
+              echo "registry=https://$NPM_REGISTRY"
+              echo "//$NPM_REGISTRY:_authToken=$NPM_TOKEN"
+            } > "$1"
+          }
+          write_npmrc "$GITHUB_WORKSPACE/.npmrc"
+        env:
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+          NPM_REGISTRY: ${{ secrets.NPM_REGISTRY }}
+
+      - name: Prepare and Process Changesets Release
+        id: changesets
+        uses: changesets/action@v1
+        with:
+          version: yarn csdk:prep-release
+          publish: yarn changeset:publish --tag latest
+          commit: '[release][ci] Version bump and changelog'
+          title: ${{ github.ref_name == 'dev' && '[csdk] latest release' || format('[csdk] patch release - {0}', github.ref_name) }}
+        env:
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+          NPM_REGISTRY: ${{ secrets.NPM_REGISTRY }}
+          GITHUB_TOKEN: ${{ steps.generate-token.outputs.token }}
+
+  canary-snapshot:
+    runs-on: ubuntu-latest
+    env:
+      YARN_ENABLE_IMMUTABLE_INSTALLS: false
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.ref }}
+          fetch-depth: 0
+
+      - name: Use Node.js 24
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+
+      - name: Install dependencies
+        run: |
+          yarn cache clean --all
+          yarn install --immutable
+
+      - name: Build packages
+        run: npm run build
+
+      - name: Creating .npmrc
+        run: |
+          NPM_REGISTRY="${NPM_REGISTRY%/}"
+          NPM_REGISTRY="${NPM_REGISTRY}/"
+          write_npmrc() {
+            {
+              echo "@sitecore-content-sdk:registry=https://$NPM_REGISTRY"
+              echo "registry=https://$NPM_REGISTRY"
+              echo "//$NPM_REGISTRY:_authToken=$NPM_TOKEN"
+            } > "$1"
+          }
+          write_npmrc "$GITHUB_WORKSPACE/.npmrc"
+        env:
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+          NPM_REGISTRY: ${{ secrets.NPM_REGISTRY }}
+
+      - name: Pre-release canary publish
+        id: canary_snapshot
+        run: yarn changeset:cascade-snapshot-version
+
+      - name: Compute snapshot npm dist-tag
+        id: snapshot_tag
+        if: steps.canary_snapshot.outputs.snapshot_publish == 'true'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const sha = context.sha;
+            const short = sha.slice(0, 7);
+            const { data } = await github.rest.repos.listPullRequestsAssociatedWithCommit({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              commit_sha: sha,
+            });
+            const prNums = data.map((p) => p.number).filter((n) => n != null);
+            const prLabel = prNums.length ? String(Math.max(...prNums)) : 'no-pr';
+            const tagPr = `canary.pr-${prLabel}`;
+            const tagSha = `canary.commit-${short}`;
+            core.setOutput('tag_pr', tagPr);
+            core.setOutput('tag_sha', tagSha);
+            core.info(`Snapshot npm dist-tags: ${tagPr} + ${tagSha}`);
+
+      - name: Publish canary snapshot packages to npm
+        if: steps.canary_snapshot.outputs.snapshot_publish == 'true'
+        env:
+          COMMIT_NPM_TAG: ${{ steps.snapshot_tag.outputs.tag_sha }}
+          PR_NPM_TAG: ${{ steps.snapshot_tag.outputs.tag_pr }}
+        run: |
+          BRANCH_NAME="${{ github.ref_name }}"
+          if [[ "$BRANCH_NAME" =~ ^release/ ]]; then
+            NPM_TAG="hotfix-canary"
+          else
+            NPM_TAG="canary"
+          fi
+          yarn changeset:publish --tag $NPM_TAG --no-git-tag
+          VERSION=$(node -p "require('./packages/create-content-sdk-app/package.json').version")
+          npm dist-tag add create-content-sdk-app@$VERSION $COMMIT_NPM_TAG
+          npm dist-tag add create-content-sdk-app@$VERSION $PR_NPM_TAG
+

lerna.json

@@ -1,8 +1,7 @@
 {
-  "lerna": "3.22.1",
   "packages": ["packages/*", "samples/*"],
   "version": "independent",
   "npmClient": "yarn",
-  "useWorkspaces": true
+  "$schema": "node_modules/lerna/schemas/lerna-schema.json"
 }