Merge branch 'main' into dependabot/npm_and_yarn/webpack-5.105.0

Author: Copilot

.devcontainer/devcontainer.json

@@ -32,9 +32,7 @@
         "golang.go",
         // Recommended for Hextra theme
         "mhutchie.git-graph",
-        "prettier.prettier-vscode",
-        "tamasfe.even-better-toml",
-        "budparr.language-hugo-vscode",
+        "esbenp.prettier-vscode",
 
         // Recommended extensions from https://gohugo.io/tools/editors/#visual-studio-code
         "eliostruyf.vscode-front-matter",
@@ -50,7 +48,7 @@
           "--whole-files",
           "--new-from-rev=origin/main"
         ],
-        "editor.defaultFormatter": "prettier.prettier-vscode",
+        "editor.defaultFormatter": "esbenp.prettier-vscode",
         "editor.tabSize": 2,
         "editor.insertSpaces": true,
         "editor.detectIndentation": false,

.github/CODEOWNERS

@@ -1,7 +1,7 @@
 
 # Default owners for all files in the repository
-* @github/github-well-architected-admins @github/cse-intelligence-engine-squad @bot-digital-customer-success @github/github-well-architected-maintainers
+# This includes CICD workflows (/.github), utility scripts for production deployments (/script), and other CSE-specific configurations
+* @github/github-well-architected-admins @github/cse-intelligence-engine-squad @bot-digital-customer-success
 
-# Owners for .github and script directories
-# This includes CICD workflows, and other CSE-specific configurations
-/.github/ @github/github-well-architected-admins @github/cse-intelligence-engine-squad @bot-digital-customer-success
+# Owners for content directory
+/content/ @github/github-well-architected-admins @github/github-well-architected-maintainers

.github/dependabot.yml

@@ -1,23 +1,52 @@
+# Dependabot version update configuration for GitHub Well-Architected Framework
+# Optimized for static site operations - balancing security with maintenance effort
+#
+# Configuration principles:
+# - Monthly scheduled updates to balance dependency freshness with maintenance effort
+# - increase-if-necessary versioning for npm to minimize breaking changes
+# - Grouped updates per ecosystem per intentional for easier review
+
 version: 2
 updates:
+  # GitHub Actions dependencies
   - package-ecosystem: "github-actions"
-    directory: "/"
+    directory: "/.github/workflows"
     schedule:
-      interval: "daily"
-    labels:
-      - "CI/CD"
-      - "dependabot"
+      # Monthly scheduled updates to balance freshness with maintenance effort; security updates can still be raised separately
+      interval: "monthly"
     commit-message:
-      prefix: ci
+      prefix: "chore(deps)"
+    reviewers:
+      - "github/cse-intelligence-engine-squad"
+    # Group version and security updates separately.
     groups:
-      actions-deps:
+      actions-version:
+        applies-to: version-updates
+        patterns:
+          - "*"
+      actions-security:
+        applies-to: security-updates
         patterns:
           - "*"
+
+  # NPM dependencies (Hugo site and tooling)
   - package-ecosystem: "npm"
     directory: "/"
     schedule:
-      interval: "daily"
+      # Monthly scheduled updates to balance freshness with maintenance effort; security updates can still be raised separately
+      interval: "monthly"
+    commit-message:
+      prefix: "chore(deps)"
+    versioning-strategy: increase-if-necessary
+    reviewers:
+      - "github/cse-intelligence-engine-squad"
+    # Group version and security updates separately.
     groups:
-      npm-deps:
+      npm-version:
+        applies-to: version-updates
+        patterns:
+          - "*"
+      npm-security:
+        applies-to: security-updates
         patterns:
           - "*"

.github/dependency-review-config.yml

@@ -1,11 +1,14 @@
-fail-on-severity: moderate
+# Dependency review configuration for GitHub Well-Architected Framework
+# Optimized for static site operations - balancing security with maintenance effort
 
-comment-summary-in-pr: always
+# Only fail on high severity vulnerabilities (includes both high and critical severity levels)
+fail-on-severity: high
 
-# allow-licenses:
-#   - MIT
+# Always provide PR comments summarizing dependency changes
+comment-summary-in-pr: always
 
+# Only fail on runtime and unknown scope vulnerabilities
+# Development dependencies are excluded to reduce noise for this static site
 fail-on-scopes:
-  - development
   - runtime
   - unknown

.github/workflows/deploy-merged-pr.yml

@@ -11,6 +11,38 @@ permissions:
   actions: read
 
 jobs:
+  check-file-changes:
+    if: github.event.review.state == 'approved'
+    runs-on: ubuntu-latest
+    env:
+      PR_NUMBER: ${{ github.event.pull_request.number }}
+      SOURCE_REPO: ${{ github.repository }}
+    outputs:
+      should_sync: ${{ steps.filter.outputs.should_sync }}
+    steps:
+      - name: Check Changed File Paths
+        id: filter
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          EXCLUDED_PATHS=(
+            ".github/workflows/"
+          )
+
+          CHANGED_FILES=$(gh pr view $PR_NUMBER --json files --repo $SOURCE_REPO --jq '[.files[].path]')
+
+          EXCLUDE_FILTER=$(printf '"%s",' "${EXCLUDED_PATHS[@]}")
+          EXCLUDE_FILTER="[${EXCLUDE_FILTER%,}]"
+
+          NON_WORKFLOW_CHANGES=$(echo "$CHANGED_FILES" | jq --argjson exclude "$EXCLUDE_FILTER" '[.[] | select(. as $f | $exclude | any(. as $p | $f | startswith($p)) | not)] | length')
+          if [ "$NON_WORKFLOW_CHANGES" -gt 0 ]; then
+            echo "PR contains changes outside filtered paths — proceeding."
+            echo "should_sync=true" >> $GITHUB_OUTPUT
+          else
+            echo "All changes are under filtered paths — skipping workflow."
+            echo "should_sync=false" >> $GITHUB_OUTPUT
+          fi
+
   check-merge-state:
     if: github.event.review.state == 'approved'
     runs-on: ubuntu-latest
@@ -75,7 +107,7 @@ jobs:
       # OSS App
       - name: Generate GitHub App Token
         id: pr_app_token
-        uses: actions/create-github-app-token@v2
+        uses: actions/create-github-app-token@v3
         with:
           app-id: ${{ vars.WELLARCHITECTED_OSS_APP_ID }}
           private-key: ${{ secrets.WELLARCHITECTED_OSS_APP_PRIVATE_KEY }}
@@ -95,8 +127,8 @@ jobs:
           echo "Auto-merge enabled successfully!"
 
   dispatch-to-internal:
-    needs: check-merge-state
-    if: needs.check-merge-state.outputs.checks_passed == 'true' && github.event.review.state == 'approved'
+    needs: [check-file-changes, check-merge-state]
+    if: needs.check-merge-state.outputs.checks_passed == 'true' && needs.check-file-changes.outputs.should_sync == 'true' && github.event.review.state == 'approved'
     runs-on: ubuntu-latest
     env:
       SOURCE_REPO: github/github-well-architected
@@ -108,7 +140,7 @@ jobs:
       # OSS App
       - name: Generate GitHub App Token
         id: dispatch_app_token
-        uses: actions/create-github-app-token@v2
+        uses: actions/create-github-app-token@v3
         with:
           app-id: ${{ vars.WELLARCHITECTED_OSS_APP_ID }}
           private-key: ${{ secrets.WELLARCHITECTED_OSS_APP_PRIVATE_KEY }}

.github/workflows/op-stale.yml

@@ -0,0 +1,24 @@
+name: "Close stale issues and PRs"
+on:
+  schedule:
+   - cron: '0 0 * * *' # Runs every day at midnight
+
+jobs:
+  stale:
+    permissions:
+      issues: write
+      pull-requests: write
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/stale@b5d41d4e1d5dceea10e7104786b73624c18a190f # v10.2.0
+      with:
+        repo-token: ${{ secrets.GITHUB_TOKEN }}
+        stale-issue-message: 'Thanks for opening this issue! To keep the project healthy, we close inactive issues after some time. There has not been any activity in the last 28 days - if you are still working on this or feel it should remain open, just leave a quick comment in the next 7 days to let us know where things are at. We really appreciate your input!'
+        stale-pr-message: 'Thanks for raising this PR! To keep the project healthy, we close inactive PRs after some time. There has not been any activity in the last 28 days - if you are still working on this or feel it should remain open, just leave a quick comment in the next 7 days to let us know where things are at. We really appreciate your input!'
+        close-issue-message: 'Closing this issue as it has been marked stale and has not received any updates in the past 7 days. If you are still working on this or believe it should be reopened, feel free to leave an update. Thanks again for contributing!'
+        close-pr-message: 'Closing this PR as it has been marked stale and has not received any updates in the past 7 days. If you are still working on this or believe it should be reopened, feel free to leave an update. Thanks again for contributing!'
+        stale-issue-label: 'stale'
+        stale-pr-label: 'stale'
+        exempt-pr-labels: 'dependencies'
+        days-before-stale: 28
+        days-before-close: 7

.github/workflows/pr-check.yml

@@ -15,6 +15,7 @@ env:
   CI: development
   SITE_DIR: public
   HUGO_VERSION: 0.151.0
+  DART_SASS_VERSION: 1.99.0
 
 jobs:
   lint:
@@ -35,7 +36,7 @@ jobs:
       - name: Install dependencies
         run: npm ci -o
 
-      - uses: super-linter/super-linter/slim@61abc07d755095a68f4987d1c2c3d1d64408f1f9 # v8.5.0
+      - uses: super-linter/super-linter/slim@9e863354e3ff62e0727d37183162c4a88873df41 # v8.6.0
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           DEFAULT_BRANCH: main
@@ -49,14 +50,11 @@ jobs:
       actions: write
       checks: write
       contents: read
-      id-token: write
-      pages: write
       pull-requests: write
       security-events: write
 
     environment:
       name: development
-      url: ${{ steps.deployment.outputs.page_url }}
 
     runs-on: ubuntu-latest
 
@@ -67,7 +65,7 @@ jobs:
           fetch-depth: 0
 
       - name: Dependency Review
-        uses: actions/dependency-review-action@v4
+        uses: actions/dependency-review-action@v5
         with:
           config-file: >-
             ./.github/dependency-review-config.yml
@@ -77,13 +75,16 @@ jobs:
           wget -O ${{ runner.temp }}/hugo.deb https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb
           sudo dpkg -i ${{ runner.temp }}/hugo.deb
           hugo version
-      - name: Install Dart Sass
-        run: sudo snap install dart-sass
 
       - uses: actions/setup-node@v6
         with:
           node-version: lts/*
 
+      - name: Install Dart Sass
+        run: |
+          npm install -g sass@${DART_SASS_VERSION}
+          sass --version
+
       - name: Install test dependencies
         run: |
           # Clean install of the node modules
@@ -114,10 +115,6 @@ jobs:
             exit 1
           fi
 
-      - name: Setup Pages
-        uses: actions/configure-pages@v5
-        id: setup-pages
-
       - name: Build site
         run: |
           hugo --gc --minify --baseURL "/"
@@ -128,18 +125,6 @@ jobs:
             echo "::warning title=Invalid file permissions automatically fixed::$line"
           done
 
-      - name: Upload Pages artifact
-        uses: actions/upload-pages-artifact@v4
-        with:
-          path: './${{ env.SITE_DIR }}'
-          retention-days: '7'
-
-      - name: Deploy site to GitHub Pages
-        id: deployment
-        uses: actions/deploy-pages@v4
-        with:
-          preview: true
-
       - name: HTML Proofer
         uses: chabad360/htmlproofer@c2750eb7eb937599ac859517e7dd23a29f1b3ed7 # v2
         with:
@@ -150,7 +135,7 @@ jobs:
         run: |
           npm run test:functional
 
-      - uses: actions/upload-artifact@v6
+      - uses: actions/upload-artifact@v7
         if: always()
         with:
           name: playwright-report

CONTRIBUTING.md

@@ -133,18 +133,13 @@ Once you're ready to start, fork the repository and begin authoring. We **strong
 
 There are three options to create a new article:
 
-##### 1. Copy/paste the template into a new file
-
-Simply copy [`archetypes/default.md`] and paste it into:
-
-```plaintext
-content/library/{PILLAR}/recommendations/{ARTICLE-NAME}.md
-```
-
-##### 2. Use the command `hugo new content` to create a new file (recommended in Codespaces)
+##### Option 1. Use the command `hugo new content` to create a new file (recommended in Codespaces)
 
 ```shell
+# For recommendations:
 hugo new content library/{PILLAR}/recommendations/{ARTICLE-NAME}.md
+# For scenarios:
+hugo new content library/scenarios/{ARTICLE-NAME}.md
 ```
 
 For example,
@@ -156,7 +151,7 @@ hugo new content library/productivity/recommendations/my-article.md
 > [!IMPORTANT]
 > When you use this method, you do not need to put `content/` in the command since Hugo considers it the root.
 
-##### 3. Use a page bundle to create a new article with associated files like images
+##### Option 2. Use a page bundle to create a new article with associated files like images
 
 Add a folder (instead of one markdown file) at that location and bundle the files together. The format is:
 
@@ -166,6 +161,22 @@ content/library/{PILLAR}/recommendations/{ARTICLE-NAME}/image1.png
 content/library/{PILLAR}/recommendations/{ARTICLE-NAME}/image2.png
 ```
 
+##### Option 3. Copy/paste the template into a new file
+
+Simply copy [`archetypes/default.md`] and paste it into:
+
+For **recommendation** articles:
+
+```plaintext
+content/library/{PILLAR}/recommendations/{ARTICLE-NAME}.md
+```
+
+For **scenario** articles:
+
+```plaintext
+content/library/scenarios/{ARTICLE-NAME}.md
+```
+
 ##### Writing Style:
 
 - Always use sentence case
@@ -185,9 +196,10 @@ publishDate: 2024-12-05 # Date the article is published
 
 # Add author details
 params:
-  author:
-    name: Mona
-    handle: octocat
+  authors:
+    [
+      { name: 'Mona', handle: 'octocat' },
+    ]
 
 # Classifications of the framework to drive key concepts, design principles, and architectural best practices
 pillars:
@@ -198,6 +210,8 @@ pillars:
 
 - When you are done with your article, set `draft: false` when you are ready to publish.
 
+- Set `publishDate` to the date the article is first merged to `main`. Do not change it on future revisions.
+
 - All recommended values for all of these fields are described in [Taxonomies]. **Insert all that apply to your article. This is how your article will be discoverable!**
 
 ---
@@ -411,7 +425,7 @@ See [Framework Overview] for details on each pillar.
 - Keep sentences **short and clear**
 - Avoid unnecessary jargon
 - Include practical examples
-- Prefer GitHub Docs links to **Enterprise Cloud**: `https://docs.github.com/en/enterprise-cloud@latest` (unless the guidance is specific to GitHub Enterprise Server)
+- Prefer GitHub Docs links to **Enterprise Cloud**: `https://docs.github.com/enterprise-cloud@latest` (unless the guidance is specific to GitHub Enterprise Server)
 - Use Hugo shortcodes to keep articles consistent (see `archetypes/default.md`):
   - Further assistance: `{{% seeking-further-assistance-details %}}`
   - Related links: `{{% related-links-github-docs %}}`