ci workflow changes for release branches

Author: clavery

.github/workflows/ci.yml

@@ -5,9 +5,11 @@ on:
     branches:
       - main
       - 'renovate/**'
+      - 'release/**'
   pull_request:
     branches:
       - main
+      - 'release/**'
 
 permissions:
   contents: read

.github/workflows/deploy-docs.yml

@@ -54,16 +54,17 @@ jobs:
       - name: Get latest release tag
         id: release
         run: |
-          # Find the most recent package tag and docs tag
-          PKG_TAG=$(git describe --tags --abbrev=0 --match '@salesforce/*' 2>/dev/null || echo "")
-          DOCS_TAG=$(git describe --tags --abbrev=0 --match 'docs@*' 2>/dev/null || echo "")
+          # Find the most recent package tag and docs tag across all branches
+          # (git describe only finds ancestor tags; git tag --list finds all)
+          PKG_TAG=$(git tag --list '@salesforce/*' --sort=-creatordate | head -n1)
+          DOCS_TAG=$(git tag --list 'docs@*' --sort=-creatordate | head -n1)
 
-          # Pick whichever tag is closer to HEAD (fewer commits behind)
+          # Pick whichever tag was created most recently
           LATEST_TAG=""
           if [[ -n "$PKG_TAG" && -n "$DOCS_TAG" ]]; then
-            PKG_DISTANCE=$(git rev-list --count "${PKG_TAG}..HEAD")
-            DOCS_DISTANCE=$(git rev-list --count "${DOCS_TAG}..HEAD")
-            if [[ "$DOCS_DISTANCE" -le "$PKG_DISTANCE" ]]; then
+            PKG_TS=$(git for-each-ref --format='%(creatordate:unix)' "refs/tags/${PKG_TAG}")
+            DOCS_TS=$(git for-each-ref --format='%(creatordate:unix)' "refs/tags/${DOCS_TAG}")
+            if [[ "$DOCS_TS" -ge "$PKG_TS" ]]; then
               LATEST_TAG="$DOCS_TAG"
             else
               LATEST_TAG="$PKG_TAG"
@@ -77,15 +78,9 @@ jobs:
           echo "tag=$LATEST_TAG" >> $GITHUB_OUTPUT
           echo "exists=$([[ -n $LATEST_TAG ]] && echo true || echo false)" >> $GITHUB_OUTPUT
 
-      - name: Read CLI version for display
-        id: cli-version
-        run: |
-          CLI_VERSION=$(node -p "require('./packages/b2c-cli/package.json').version")
-          echo "version=$CLI_VERSION" >> $GITHUB_OUTPUT
-
       - name: Build dev documentation
         run: |
-          IS_DEV_BUILD=true RELEASE_VERSION=${{ steps.cli-version.outputs.version }} pnpm run docs:build
+          IS_DEV_BUILD=true pnpm run docs:build
           mv docs/.vitepress/dist docs/.vitepress/dist-dev
 
       - name: Build stable documentation from release tag
@@ -114,7 +109,7 @@ jobs:
           # Build at release tag with main's config (no IS_DEV_BUILD = stable at root)
           pnpm install --frozen-lockfile
           pnpm -r run build
-          RELEASE_VERSION=${{ steps.cli-version.outputs.version }} pnpm run docs:build
+          pnpm run docs:build
 
           # Combine: stable at root, dev in /dev/
           mv docs/.vitepress/dist-dev docs/.vitepress/dist/dev

.github/workflows/publish.yml

@@ -1,12 +1,16 @@
 name: Publish to npm
 
 on:
+  workflow_run:
+    workflows: ["CI"]
+    types: [completed]
+    branches: ['release/**']
   schedule:
     - cron: '0 2 * * 1-5' # Weekdays at 2 AM UTC (Mon-Fri)
   workflow_dispatch:
     inputs:
       release_type:
-        description: 'Release type'
+        description: 'Release type (ignored for release branch workflow_run — always stable)'
         required: true
         default: 'nightly'
         type: choice
@@ -21,44 +25,96 @@ jobs:
   publish:
     name: Publish
     runs-on: ubuntu-latest
+    if: >-
+      github.event_name != 'workflow_run' ||
+      github.event.workflow_run.conclusion == 'success'
     permissions:
       contents: write # For creating GitHub releases and tags
       id-token: write # Required for npm OIDC trusted publishers
+      pull-requests: write # For creating merge-back PRs
     steps:
       - name: Checkout
         uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
         with:
+          ref: ${{ github.event_name == 'workflow_run' && github.event.workflow_run.head_branch || '' }}
           fetch-depth: 0 # Needed for docs tag detection
 
       - name: Determine release type
         id: release-type
         run: |
-          if [[ "${{ github.event.inputs.release_type }}" == "stable" ]]; then
+          if [[ "${{ github.event.inputs.release_type }}" == "stable" ]] || [[ "${{ github.event_name }}" == "workflow_run" ]]; then
             echo "type=stable" >> $GITHUB_OUTPUT
             echo "tag=latest" >> $GITHUB_OUTPUT
           else
             echo "type=nightly" >> $GITHUB_OUTPUT
             echo "tag=nightly" >> $GITHUB_OUTPUT
           fi
 
+      - name: Check for pending changesets
+        if: steps.release-type.outputs.type == 'stable'
+        id: changesets
+        run: |
+          PENDING=$(find .changeset -name '*.md' ! -name 'README.md' 2>/dev/null | wc -l | tr -d ' ')
+          if [[ "$PENDING" -gt 0 ]]; then
+            echo "skip=true" >> $GITHUB_OUTPUT
+            echo "::notice::Found $PENDING pending changeset(s) — skipping publish"
+          else
+            echo "skip=false" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Quick version check
+        if: steps.release-type.outputs.type == 'stable' && steps.changesets.outputs.skip != 'true'
+        id: quick-check
+        run: |
+          HAS_CHANGES=false
+          for spec in "@salesforce/b2c-tooling-sdk:packages/b2c-tooling-sdk" \
+                      "@salesforce/b2c-cli:packages/b2c-cli" \
+                      "@salesforce/b2c-dx-mcp:packages/b2c-dx-mcp"; do
+            PKG_NAME="${spec%%:*}"
+            PKG_PATH="${spec##*:}"
+            LOCAL=$(node -p "require('./${PKG_PATH}/package.json').version")
+            NPM=$(npm view "$PKG_NAME" version 2>/dev/null || echo "0.0.0")
+            if [ "$LOCAL" != "$NPM" ]; then
+              HAS_CHANGES=true
+              break
+            fi
+          done
+          # Also check docs tag
+          if [ "$HAS_CHANGES" = "false" ]; then
+            DOCS_VERSION=$(node -p "require('./docs/package.json').version")
+            if ! git rev-parse "docs@${DOCS_VERSION}" >/dev/null 2>&1; then
+              HAS_CHANGES=true
+            fi
+          fi
+          if [ "$HAS_CHANGES" = "false" ]; then
+            echo "skip=true" >> $GITHUB_OUTPUT
+            echo "::notice::All package versions match npm — nothing to publish"
+          else
+            echo "skip=false" >> $GITHUB_OUTPUT
+          fi
+
       - name: Setup pnpm
+        if: steps.release-type.outputs.type == 'nightly' || (steps.changesets.outputs.skip != 'true' && steps.quick-check.outputs.skip != 'true')
         uses: pnpm/action-setup@41ff72655975bd51cab0327fa583b6e92b6d3061 # v4
 
       - name: Setup Node.js
+        if: steps.release-type.outputs.type == 'nightly' || (steps.changesets.outputs.skip != 'true' && steps.quick-check.outputs.skip != 'true')
         uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
         with:
           node-version: 22
           cache: 'pnpm'
           registry-url: 'https://registry.npmjs.org'
 
       - name: Upgrade npm for trusted publishing
+        if: steps.release-type.outputs.type == 'nightly' || (steps.changesets.outputs.skip != 'true' && steps.quick-check.outputs.skip != 'true')
         run: npm install -g npm@latest
 
       - name: Install dependencies
+        if: steps.release-type.outputs.type == 'nightly' || (steps.changesets.outputs.skip != 'true' && steps.quick-check.outputs.skip != 'true')
         run: pnpm install --frozen-lockfile
 
       - name: Determine packages to publish
-        if: steps.release-type.outputs.type == 'stable'
+        if: steps.release-type.outputs.type == 'stable' && steps.changesets.outputs.skip != 'true' && steps.quick-check.outputs.skip != 'true'
         id: packages
         run: |
           check_package() {
@@ -74,6 +130,19 @@ jobs:
             if [ "$LOCAL_VERSION" != "$NPM_VERSION" ]; then
               echo "publish_${output_key}=true" >> $GITHUB_OUTPUT
               echo "version_${output_key}=${LOCAL_VERSION}" >> $GITHUB_OUTPUT
+
+              # Determine appropriate npm dist-tag via semver comparison
+              IS_NEWER=$(node -e "
+                const [a,b,c] = '${LOCAL_VERSION}'.split('.').map(Number);
+                const [x,y,z] = '${NPM_VERSION}'.split('.').map(Number);
+                console.log(a>x||(a===x&&(b>y||(b===y&&c>z))));
+              ")
+              if [ "$IS_NEWER" = "true" ]; then
+                echo "tag_${output_key}=latest" >> $GITHUB_OUTPUT
+              else
+                MINOR=$(echo "$LOCAL_VERSION" | sed 's/\.[0-9]*$//')
+                echo "tag_${output_key}=release-${MINOR}" >> $GITHUB_OUTPUT
+              fi
             else
               echo "publish_${output_key}=false" >> $GITHUB_OUTPUT
             fi
@@ -109,25 +178,33 @@ jobs:
           echo "Set snapshot version: $SNAPSHOT"
 
       - name: Build packages
+        if: steps.release-type.outputs.type == 'nightly' || (steps.changesets.outputs.skip != 'true' && steps.quick-check.outputs.skip != 'true')
         run: pnpm run build
 
       - name: Run tests
+        if: steps.release-type.outputs.type == 'nightly' || (steps.changesets.outputs.skip != 'true' && steps.quick-check.outputs.skip != 'true')
         run: pnpm --filter '!b2c-vs-extension' run test
 
       - name: Publish SDK to npm
         if: steps.release-type.outputs.type == 'nightly' || steps.packages.outputs.publish_sdk == 'true'
-        run: pnpm --filter @salesforce/b2c-tooling-sdk publish --provenance --no-git-checks --tag ${{ steps.release-type.outputs.tag }}
+        run: >-
+          pnpm --filter @salesforce/b2c-tooling-sdk publish --provenance --no-git-checks
+          --tag ${{ steps.release-type.outputs.type == 'nightly' && 'nightly' || steps.packages.outputs.tag_sdk }}
 
       - name: Publish CLI to npm
         if: steps.release-type.outputs.type == 'nightly' || steps.packages.outputs.publish_cli == 'true'
-        run: pnpm --filter @salesforce/b2c-cli publish --provenance --no-git-checks --tag ${{ steps.release-type.outputs.tag }}
+        run: >-
+          pnpm --filter @salesforce/b2c-cli publish --provenance --no-git-checks
+          --tag ${{ steps.release-type.outputs.type == 'nightly' && 'nightly' || steps.packages.outputs.tag_cli }}
 
       - name: Publish MCP to npm
         if: steps.release-type.outputs.type == 'nightly' || steps.packages.outputs.publish_mcp == 'true'
-        run: pnpm --filter @salesforce/b2c-dx-mcp publish --provenance --no-git-checks --tag ${{ steps.release-type.outputs.tag }}
+        run: >-
+          pnpm --filter @salesforce/b2c-dx-mcp publish --provenance --no-git-checks
+          --tag ${{ steps.release-type.outputs.type == 'nightly' && 'nightly' || steps.packages.outputs.tag_mcp }}
 
       - name: Create git tags
-        if: steps.release-type.outputs.type == 'stable'
+        if: steps.release-type.outputs.type == 'stable' && steps.changesets.outputs.skip != 'true' && steps.quick-check.outputs.skip != 'true'
         run: |
           git config user.name "github-actions[bot]"
           git config user.email "github-actions[bot]@users.noreply.github.com"
@@ -160,15 +237,15 @@ jobs:
           fi
 
       - name: Create docs tag if version changed
-        if: steps.release-type.outputs.type == 'stable' && steps.packages.outputs.publish_docs == 'true'
+        if: steps.release-type.outputs.type == 'stable' && steps.changesets.outputs.skip != 'true' && steps.quick-check.outputs.skip != 'true' && steps.packages.outputs.publish_docs == 'true'
         run: |
           DOCS_TAG="docs@${{ steps.packages.outputs.version_docs }}"
           git tag "$DOCS_TAG"
           git push origin "$DOCS_TAG"
           echo "Created docs tag: $DOCS_TAG"
 
       - name: Extract changelogs for release
-        if: steps.release-type.outputs.type == 'stable'
+        if: steps.release-type.outputs.type == 'stable' && steps.changesets.outputs.skip != 'true' && steps.quick-check.outputs.skip != 'true'
         run: |
           # Function to extract the latest version section from a changelog
           extract_latest() {
@@ -210,7 +287,7 @@ jobs:
           } > /tmp/release-notes.md
 
       - name: Create GitHub Release
-        if: steps.release-type.outputs.type == 'stable'
+        if: steps.release-type.outputs.type == 'stable' && steps.changesets.outputs.skip != 'true' && steps.quick-check.outputs.skip != 'true'
         run: |
           # Determine the release tag — prefer CLI as the user-facing product
           if [[ "${{ steps.packages.outputs.publish_cli }}" == "true" ]]; then
@@ -231,7 +308,7 @@ jobs:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Package skills artifacts
-        if: steps.release-type.outputs.type == 'stable'
+        if: steps.release-type.outputs.type == 'stable' && steps.changesets.outputs.skip != 'true' && steps.quick-check.outputs.skip != 'true'
         run: |
           # Create b2c-skills.zip containing skills/b2c/skills/
           cd skills/b2c && zip -r ../../b2c-skills.zip skills/
@@ -243,7 +320,7 @@ jobs:
           ls -la *.zip
 
       - name: Upload skills to release
-        if: steps.release-type.outputs.type == 'stable'
+        if: steps.release-type.outputs.type == 'stable' && steps.changesets.outputs.skip != 'true' && steps.quick-check.outputs.skip != 'true'
         run: |
           # Determine the release tag (same logic as Create GitHub Release)
           if [[ "${{ steps.packages.outputs.publish_cli }}" == "true" ]]; then
@@ -262,7 +339,32 @@ jobs:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Trigger documentation deployment
-        if: steps.release-type.outputs.type == 'stable'
+        if: steps.release-type.outputs.type == 'stable' && steps.changesets.outputs.skip != 'true' && steps.quick-check.outputs.skip != 'true'
         run: gh workflow run deploy-docs.yml
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Create PR to merge version bumps back to main
+        if: github.event_name == 'workflow_run'
+        run: |
+          if [[ "${{ steps.packages.outputs.publish_sdk }}" == "true" ]] || \
+             [[ "${{ steps.packages.outputs.publish_cli }}" == "true" ]] || \
+             [[ "${{ steps.packages.outputs.publish_mcp }}" == "true" ]] || \
+             [[ "${{ steps.packages.outputs.publish_docs }}" == "true" ]]; then
+            BRANCH="${{ github.event.workflow_run.head_branch }}"
+            gh pr create --base main --head "$BRANCH" \
+              --title "Merge version bumps from ${BRANCH}" \
+              --body "$(cat <<'EOF'
+          Auto-created after hotfix publish from `'"${BRANCH}"'`.
+
+          Merges version bump commits back to main to prevent version collisions on the next regular release.
+
+          **Review checklist:**
+          - [ ] Version bumps in package.json files look correct
+          - [ ] CHANGELOG entries are accurate
+          - [ ] No merge conflicts with pending changesets on main
+          EOF
+          )" || echo "::warning::PR already exists or could not be created"
+          fi
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

CONTRIBUTING.md

@@ -74,8 +74,9 @@ Add a changeset when your PR includes changes that users should know about:
 - Breaking changes
 - Significant improvements
 
+For **documentation-only changes** (new guides, restructured content, significant improvements) that should be deployed before the next package release, create a changeset targeting `@salesforce/b2c-dx-docs`. This triggers a doc-only release and rebuild. Routine doc fixes (typos, minor clarifications) that can wait for the next package release don't need a changeset.
+
 You **don't need** a changeset for:
-- Documentation-only changes
 - Internal refactoring
 - Test improvements
 - CI/build changes
@@ -102,6 +103,7 @@ You **don't need** a changeset for:
 
 - Changesets are optional - maintainers can add them later if needed
 - Multiple changesets can exist for separate changes
+- For **hotfix releases** (urgent patches while unrelated changesets are pending on `main`), maintainers use release branches — see [PUBLISHING.md](./PUBLISHING.md#hotfix-release) for details
 - See [PUBLISHING.md](./PUBLISHING.md) for full release process details
 
 # Creating a Pull Request