ci(docs): stage 2nd-gen docs on merge, gate prod publish behind #gen2-publish

[blunteshwar]

Description

Splits the 2nd-gen documentation deploy into two targets so the public site can stay in sync with releases instead of updating on every merge:

• Staging — every push to main (non-1st-gen changes) syncs to $web/docs-staging/ (https://swcpreviews.z13.web.core.windows.net/docs-staging/). This preserves the always-latest environment we have today.
• Production — $web/docs/ (mapped to spectrum-web-components.adobe.com) now deploys only on a manual workflow_dispatch or a push to main whose commit message contains #gen2-publish.

The keyword is #gen2-publish rather than #publish on purpose: the 1st-gen publish-docs-site.yml matches on the #publish substring, so a shared keyword would couple the two sites. #gen2-publish does not contain #publish, keeping them independent.

publish-2nd-gen.yml's Version PR title now includes #gen2-publish too (chore: release 2nd-gen packages (beta) #gen2-publish) — the actual release event is the squash-merge of that PR, and squash merges use the PR title as the merge commit message on main (confirmed against this repo's own release-commit history, e.g. chore: release packages #publish (#6470)). Without this, the keyword would only ever appear on a manual workflow_dispatch, and the production docs site would never sync with a real gen2 release.

Motivation and context

We're moving into pre-release/beta publishing and want the public 2nd-gen docs site to update in sync with announced releases, not on every merge. Staging keeps tracking main for day-to-day validation.

Rebased onto the current release-strategy base (post gen1/gen2 changesets split in #6607) — the docs-deploy workflow itself is orthogonal to package publishing, but its production trigger needed to be wired to the actual release event under the new Version PR flow.

Related issue(s)

• SWC-2487

Screenshots (if appropriate)

N/A — CI/documentation-deploy change only; no component or runtime UI is modified.

Author's checklist

• I have read the CONTRIBUTING and PULL_REQUESTS documents.
• I have reviewed at the Accessibility Practices for this feature — N/A, no UI surface.
• I have added automated tests to cover my changes — N/A, workflow YAML isn't unit-testable in this repo; validated via manual review of the if: gating logic and this repo's historical squash-merge commit messages.
• I have included a well-written changeset if my change needs to be published — N/A, CI/docs-only, no published package changed.
• I have included updated documentation if my change required it (CONTRIBUTOR-DOCS/01_contributor-guides/06_releasing-swc.md).

Reviewer's checklist

• Includes a GitHub Issue with appropriate flag or Jira ticket number without a link
• Automated tests cover all use cases and follow best practices for writing
• Validated on all supported browsers
• All VRTs are approved before the author can update Golden Hash

Manual review test cases

• Staging deploys on merge

  1. Merge a non-1st-gen change to main.
  2. Confirm Publish 2nd-Gen Documentation runs the "Deploy to staging" step and skips "Deploy to production".
  3. Verify https://swcpreviews.z13.web.core.windows.net/docs-staging/ reflects the change.

• Production deploys on a real gen2 release

  1. Merge the 2nd-gen Version PR (chore: release 2nd-gen packages (beta) #gen2-publish) opened by publish-2nd-gen.yml.
  2. Confirm the resulting squash-merge commit message on main contains #gen2-publish.
  3. Confirm both "Deploy to staging" and "Deploy to production" run.
  4. Verify spectrum-web-components.adobe.com reflects the change.

• Production deploys on manual dispatch

  1. Run Publish 2nd-Gen Documentation via workflow_dispatch.
  2. Confirm both steps run regardless of the latest commit message.

• No cross-trigger with 1st-gen

  1. Confirm a #gen2-publish commit does not trigger Publish Documentation Site (1st-gen).

Device review

• Did it pass in Desktop? (N/A — no UI)
• Did it pass in (emulated) Mobile? (N/A — no UI)
• Did it pass in (emulated) iPad? (N/A — no UI)

Accessibility testing checklist

N/A — this PR only changes CI/documentation-deploy configuration; no component, page, or interactive surface is affected. No keyboard or screen reader testing applies.

• Keyboard (required — document steps below)

  1. N/A — no focusable UI is added or changed by this workflow/docs update.

• Screen reader (required — document steps below)

  1. N/A — no roles, names, or announcements are affected by this workflow/docs update.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 1ada46e

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[github-actions]

📚 Branch Preview Links

• Storybook (Gen2, dev mode)
• Storybook (Gen2, prod mode)
• Documentation Site (Gen1)
• Storybook (Gen1)

🔍 Gen1 Visual Regression Test Results

When a visual regression test fails (or has previously failed while working on this branch), its results can be found in the following URLs:

• Spectrum | Light | Medium | LTR
• Spectrum | Dark | Large | RTL
• Express | Light | Medium | LTR
• Express | Dark | Large | RTL
• Spectrum-two | Light | Medium | LTR
• Spectrum-two | Dark | Large | RTL
• High Contrast Mode | Medium | LTR

Deployed to Azure Blob Storage: pr-6637

If the changes are expected, update the current_golden_images_cache hash in the circleci config to accept the new images. Instructions are included in that file.
If the changes are unexpected, you can investigate the cause of the differences and update the code accordingly.