chore: add beta release workflow action (#4798)

.circleci/config.yml

@@ -219,6 +219,20 @@ jobs:
                   branch=$(npx slugify-cli $branch)
                   yarn netlify deploy --alias=$branch --cwd projects/documentation
 
+    beta-docs:
+        executor: node
+
+        steps:
+            - downstream
+            - run:
+                  name: Generate Beta Docs
+                  command: yarn docs:preview
+            - run: echo '/*    /index.html   200' > projects/documentation/dist/_redirects
+            - run: |
+                  branch=$(git symbolic-ref --short HEAD)
+                  branch=$(npx slugify-cli $branch)
+                  yarn netlify deploy --alias=beta --cwd projects/documentation
+
     hcm-visual:
         executor: node
 
@@ -329,6 +343,11 @@ workflows:
                       branches:
                           # Forked pull requests have CIRCLE_BRANCH set to pull/XXX
                           ignore: /pull\/[0-9]+/
+            - beta-docs:
+                  filters:
+                      branches:
+                          # Beta docs are only published from main
+                          only: main
             - visual:
                   name: << matrix.theme >>-<< matrix.color >>-<< matrix.scale >>-<< matrix.dir >>
                   matrix:

.github/workflows/beta-release.yml

@@ -0,0 +1,84 @@
+name: Beta Release
+
+on:
+    push:
+        branches:
+            - main
+
+jobs:
+    release:
+        runs-on: ubuntu-latest
+
+        steps:
+            - name: Checkout repository
+              uses: actions/checkout@v3
+
+            - name: Set up Node.js
+              uses: actions/setup-node@v3
+              with:
+                  node-version: '20'
+
+            - name: Install dependencies
+              run: yarn install --frozen-lockfile
+
+            - name: Set Git identity
+              run: |
+                  git config --global user.email "support+actions@github.com"
+                  git config --global user.name "github-actions-bot"
+
+            - name: Get Lerna current version
+              id: get_lerna_version
+              run: |
+                  CURRENT_VERSION=$(npx lerna ls --json | jq -r '.[0].version')
+                  echo "version=$CURRENT_VERSION" >> $GITHUB_OUTPUT
+
+            - name: Calculate next minor version
+              id: calculate_next_minor_version
+              run: |
+                  NEXT_MINOR_VERSION=$(npx semver "${{ steps.get_lerna_version.outputs.version }}" -i minor)
+                  echo "next_minor_version=$NEXT_MINOR_VERSION" >> $GITHUB_OUTPUT
+
+            - name: Get latest published beta version
+              id: get_latest_published_beta
+              run: |
+                  LATEST_BETA_VERSION=$(npm view @spectrum-web-components/button@beta version || echo "none")
+                  echo "latest_beta_version=$LATEST_BETA_VERSION" >> $GITHUB_OUTPUT
+
+            - name: Calculate next beta version
+              id: calculate_next_beta_version
+              run: |
+                  NEXT_MINOR_VERSION="${{ steps.calculate_next_minor_version.outputs.next_minor_version }}"
+                  LATEST_BETA_VERSION="${{ steps.get_latest_published_beta.outputs.latest_beta_version }}"
+
+                  if [ "$LATEST_BETA_VERSION" == "none" ]; then
+                      BETA_VERSION="$NEXT_MINOR_VERSION-beta.0"
+                  else
+                      LATEST_BETA_BASE_VERSION=$(echo "$LATEST_BETA_VERSION" | sed 's/-beta\.[0-9]*//')
+
+                      if [ "$NEXT_MINOR_VERSION" != "$LATEST_BETA_BASE_VERSION" ]; then
+                          BETA_VERSION="$NEXT_MINOR_VERSION-beta.0"
+                      else
+                          CURRENT_BETA_NUMBER=$(echo "$LATEST_BETA_VERSION" | sed 's/.*-beta\.\([0-9]\+\)/\1/')
+                          NEXT_BETA_NUMBER=$((CURRENT_BETA_NUMBER + 1))
+                          BETA_VERSION="$NEXT_MINOR_VERSION-beta.$NEXT_BETA_NUMBER"
+                      fi
+                  fi
+
+                  echo "beta_version=$BETA_VERSION" >> $GITHUB_OUTPUT
+
+            - name: Update package versions for beta release
+              run: |
+                  npx lerna version "${{ steps.calculate_next_beta_version.outputs.beta_version }}" --no-git-tag-version --no-push --yes
+
+            - name: Configure NPM for Lerna publish
+              env:
+                  NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+              run: |
+                  echo "//registry.npmjs.org/:_authToken=${{ secrets.NPM_TOKEN }}" > ~/.npmrc
+
+            - name: Publish beta release
+              env:
+                  NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+              run: |
+                  git commit -am "chore: publish beta version ${{ steps.calculate_next_beta_version.outputs.beta_version }}"
+                  npx lerna publish from-package --dist-tag beta --no-git-tag-version --no-push --yes

projects/documentation/content/support-and-compatibility.md

@@ -13,6 +13,22 @@ This page provides comprehensive information on versioning, public APIs, browser
 
 Starting from version 1.0.0, Spectrum Web Components follows semantic versioning ([semver](https://semver.org/)). We regularly release patch versions, which do not contain breaking changes. When a breaking change occurs, it will be done in a major version release to avoid breaking existing applications depending on the old version. Major version releases will be communicated in advance, and migration guides will be provided.
 
+### Beta versions
+
+To provide early access to upcoming releases, we maintain a beta tag that points to the next minor version. The beta tag will always correspond to the next minor version incremented from the latest stable release. For example, if the latest tagged release is `1.2.1`, the beta tag will be `1.3.0-beta.0`.
+
+You can find the respective `beta` version of the documentation website under the following link: https://beta--spectrum-web-components.netlify.app/
+
+You can install the beta version of a specific Spectrum Web Components package by using the`@beta` tag with your package manager. For example, to install the beta version of the `@spectrum-web-components/button` package, run:
+
+```bash
+yarn add @spectrum-web-components/button@beta
+```
+
+Consumers using the beta tag can expect a relatively stable experience but should be prepared for potential changes or issues. This tag is ideal for those who want to preview or test new features before they are officially released.
+
+We encourage consumers to report any issues they encounter. Your feedback is valuable in helping us improve the final release.
+
 ## Public APIs
 
 Our public API consists of: