lint

* Enhance tap-hold docs.

* Minor edits.

* Move note on Quick Tap to a sub bullet for visibility.

Co-authored-by: Drashna Jaelre <drashna@live.com>

---------

Co-authored-by: Drashna Jaelre <drashna@live.com>

.github/copilot-instructions.md

@@ -0,0 +1,243 @@
+---
+applyTo: "keyboards/**"
+excludeAgent:
+  - "coding-agent"
+---
+# GitHub Copilot Instructions for QMK Pull Request Review
+This document provides automated review guidance based on the [QMK PR Checklist](https://docs.qmk.fm/pr_checklist) and it is intended only for use by GitHub Copilot code-review agent during pull request reviews.
+
+> **Scope**: This review applies **only to changes within the `keyboards/` folder**. Changes outside `keyboards/` (e.g., core code, quantum, platforms, drivers) must be flagged and deferred to a QMK Collaborator — do not review them.
+
+## General PR Requirements
+
+### Branch and Submission Standards
+- **Source Branch Policy**: Verify PR is NOT submitted from submitter's own `master` branch
+  - Flag if submitter is using their own `master` branch as source
+  - Suggest using feature branches instead for cleaner fork management
+- **Target Branch Policy**:
+  - **New keyboard additions** → `master` branch (new folders under `keyboards/`)
+  - **All other changes** → `develop` branch:
+    - Keyboard updates, refactors, or moves
+    - Core code changes
+    - Data-driven configuration migrations
+    - Any modifications to existing keyboards
+- **PR Scope**: PRs should contain the smallest set of modifications for a single change
+  - Flag PRs that modify multiple keyboards simultaneously
+  - Suggest splitting large PRs into focused, incremental changes
+- **Merge Conflicts**: Check for unresolved merge conflicts
+
+### File Naming and Structure
+- **Lowercase Requirement**: All new directories and filenames must be lowercase
+  - Exception: Upstream sources with original uppercase (LUFA, ChibiOS)
+  - Exception: Core files with valid justification
+  - **Reject**: Board designer preference for uppercase is NOT valid justification
+
+### License Headers
+- **Required**: Valid license headers on all `*.c` and `*.h` files
+- **Recommended**: GPL2/GPL3 for consistency
+- **Format**: Check for proper GPL2+ header or SPDX identifier
+  ```c
+  // Copyright 2024 Your Name (@yourgithub)
+  // SPDX-License-Identifier: GPL-2.0-or-later
+  ```
+- **Exception**: Simple assignment-only `rules.mk` files don't need headers
+- **Flag**: Missing or ambiguous license headers (blocks merge)
+
+---
+
+## Keymap PR Reviews
+
+**Scope**: These rules apply to files within `keyboards/*/keymaps/*` subdirectories.
+
+### Note on Non-Default Keymaps
+- Any keymap folder named something other than `default` (e.g., `default_clueboard`, `via`) is a non-default keymap
+- **Do not review the content** of non-default keymaps — flag their presence and note that a QMK Collaborator must review them
+
+### Keymap Code Standards
+- **Includes**: `#include QMK_KEYBOARD_H` preferred over specific board files
+- **Enums**: Suggest using layer enums instead of `#define`s for layers (soft suggestion only)
+- **Custom Keycodes**: First entry must be `QK_USER`
+- **VIA**: Keymaps should NOT enable VIA
+  - VIA keymaps belong in [VIA QMK Userspace](https://github.com/the-via/qmk_userspace_via)
+
+---
+
+## Keyboard PR Reviews
+
+**Scope**: These rules apply to keyboard-level files in `keyboards/*` directories, excluding files within the `keymaps/` subdirectories. This includes:
+- `info.json` or `keyboard.json` (keyboard root or variant level)
+- `readme.md` (keyboard level)
+- `rules.mk` (keyboard level)
+- `config.h` (keyboard level, not keymap level)
+- `<keyboard>.c` and `<keyboard>.h` files
+- Hardware configuration files (`halconf.h`, `mcuconf.h`, `chconf.h`)
+
+### Branch Targeting
+- **New Keyboards**: Target `master` branch
+  - New additions to `keyboards/` folder submit to `master`
+- **Keyboard Moves**: Must target `develop` branch
+  - Check `data/mappings/keyboard_aliases.hjson` is updated for moves
+- **Keyboard Updates/Refactors**: Must target `develop` to reduce merge conflicts
+- **Data Driven Migration**: Must target `develop`
+
+### info.json and keyboard.json Requirements
+- **Schema Validation**: Verify that `info.json` and `keyboard.json` files are valid JSON (no syntax errors, no trailing commas, properly closed brackets)
+- **Mandatory Elements**:
+  - `url` field is present and begins with `http://` or `https://`
+  - `maintainer` field is present and non-empty
+  - `usb.vid` and `usb.pid` fields are present and match the `0x` hexadecimal format (e.g. `"vid": "0x1234"`, `"pid": "0xFEED"`)
+  - `usb.device_version` field is present
+  - Each key entry in every `layout` array must include a `"matrix"` property (e.g. `{"label": "L01", "matrix": [0, 0], "x": 0, "y": 0}`)
+  - Microcontroller and bootloader specified
+  - Diode direction (if not using direct pins)
+- **Layout Naming**:
+  - Single layout: Must be named `LAYOUT` or match `LAYOUT_*` pattern
+  - Multiple layouts: Must include `LAYOUT_all` plus at least one alternate name
+
+### readme.md Requirements
+- **Template**: Must follow [official template](https://github.com/qmk/qmk_firmware/blob/master/data/templates/keyboard/readme.md)
+- **Flash Command**: Present with `:flash` at end
+- **Hardware Link**: Valid availability link (unless handwired)
+  - Private groupbuys acceptable
+  - Open-source should link to files
+- **Reset Instructions**: Bootloader reset instructions must be present (non-empty)
+- **Images**: A keyboard image is preferred but not mandatory
+  - If present, images must not be hosted in the repository
+  - If an imgur URL is used, it must link directly to the image (i.e. `https://i.imgur.com/<id>.<ext>`), not the preview page (i.e. not `https://imgur.com/<id>`)
+
+### rules.mk Standards
+- **Removed Items**:
+  - Size comments like `(-/+size)`
+
+### config.h Standards (Keyboard Level)
+- **Prohibited**:
+  - `#define DESCRIPTION`
+  - Comment blocks explaining features
+  - Commented-out unused defines
+  - `#include "config_common.h"`
+- **No Vial**: Vial-related files/changes not accepted
+
+### Keyboard Implementation Files
+
+#### `<keyboard>.c`
+- **Advanced Code Flag**: ⚠️ If a `<keyboard>.c` file is present in the PR, flag it as possible advanced code requiring QMK Collaborator review
+
+#### `<keyboard>.h`
+- **Include**: `#include "quantum.h"` at top
+- **Layout Macros**: If `LAYOUT` macros are present, suggest moving them to `info.json` or `keyboard.json`
+
+### Default Keymap Standards
+
+**Scope**: These rules specifically apply to files within `keyboards/*/keymaps/default/` directories.
+
+- **Pristine Requirement**: Bare minimum clean slate
+  - ⚠️ If `keymap.c` contains anything beyond the `keymaps[]` array, or if the `default` keymap folder contains additional `.c` or `.h` files, flag this as possible advanced code requiring QMK Collaborator review
+- **Removed Examples**: Delete `QMKBEST`/`QMKURL` macros
+- **Tri Layer**: Use Tri Layer feature instead of manual `layer_on/off()` + `update_tri_layer()`
+- **Encoder Map**: Use encoder map feature, `encoder_update_user()` may not be present
+- **No VIA**: Default keymap should not enable VIA
+
+### Prohibited Files
+- **No VIA JSON**: Belongs in [VIA Keyboard Repo](https://github.com/the-via/keyboards)
+- **No KLE JSON**: Not used within QMK
+- **Single Keyboard Per PR**: A PR must not modify more than one `keyboards/<folder>/` directory
+  - Flag PRs that touch multiple top-level keyboard folders (e.g., both `keyboards/mykeyboard1/` and `keyboards/mykeyboard2/`) — each keyboard must be a separate PR
+- **No Cross-Keyboard Sources**: Don't include files from other keyboard vendors
+  - Exception: Core files (e.g., `drivers/sensors/pmw3360.c`)
+  - Use of vendor-specific code (e.g., `wilba_tech/wt_main.c`) only when keyboard exists in the same enclosing vendor folder (e.g. a `wilba_tech` keyboard)
+
+---
+
+## Review Response Templates
+
+### For source master branch usage:
+```
+⚠️ This PR appears to be submitted from your own `master` branch. For future PRs, we recommend using feature branches instead of committing to your `master`. This makes it easier to keep your fork updated and manage multiple PRs.
+
+See: [Best Practices: Your Fork's Master](https://docs.qmk.fm/newbs_git_using_your_master_branch)
+```
+
+### For incorrect target branch:
+```
+❌ This PR targets the wrong branch:
+- **New keyboard additions** should target `master`
+- **Keyboard updates/refactors/moves** should target `develop`
+
+Please change the target branch accordingly.
+```
+
+### For missing license headers:
+```
+❌ Missing GPL-compatible license headers on the following files:
+- [list files]
+
+Please add GPL2+ headers (GPL2/GPL3 recommended). Example:
+\`\`\`c
+// Copyright 2024 Your Name (@yourgithub)
+// SPDX-License-Identifier: GPL-2.0-or-later
+\`\`\`
+```
+
+### For non-lowercase filenames:
+```
+❌ The following files/directories must be lowercase:
+- [list files]
+
+Exception: Only valid if from upstream sources (LUFA, ChibiOS) or justified by core consistency.
+```
+
+### For config.h violations:
+```
+⚠️ Found prohibited config.h elements:
+- [list specific issues: `#define DESCRIPTION`, `#include "config_common.h"`, comment blocks, commented-out defines]
+
+Please remove these and refer to [Data Driven Configuration](https://docs.qmk.fm/data_driven_config).
+```
+
+### For info.json or keyboard.json issues:
+```
+⚠️ info.json or keyboard.json needs attention:
+- [list missing mandatory fields]
+- Please run: \`qmk format-json -i path/to/info.json\` (or keyboard.json)
+- Validate with: \`qmk lint -kb <keyboard_name>\`
+```
+
+### For non-pristine default keymap:
+```
+⚠️ Default keymap requires collaborator review:
+The default `keymap.c` contains code beyond the `keymaps[]` array. The following was detected:
+- [describe: extra functions/definitions in keymap.c, or additional .c/.h files in the default keymap folder]
+
+A QMK Collaborator must review this before merging.
+```
+
+### For non-default keymaps:
+```
+⚠️ Non-default keymap detected: `keyboards/[path]/keymaps/[name]/`
+
+This keymap requires a QMK Collaborator to review its content. No automated review of its code was performed.
+```
+
+### For `<keyboard>.c` detected:
+```
+⚠️ `<keyboard>.c` file detected: `keyboards/[path]/[keyboard].c`
+
+This file may contain advanced hardware configuration. A QMK Collaborator must review this before merging.
+```
+
+---
+
+## Constraints and Conduct
+
+- **Scope**: Only review changes within the `keyboards/` folder. Flag any changes outside `keyboards/` and defer to a QMK Collaborator without reviewing them.
+- Focus reviews on **objective checklist items** that can be automatically verified
+- Flag **definite violations** with ❌
+- Suggest improvements for **recommendations** with ⚠️
+- **Provide specific file/line references** when flagging issues
+- **Link to relevant QMK documentation** for each issue
+- **Prioritize blocking issues** (license, merge conflicts, branch policy)
+- **Be constructive**: Suggest fixes, not just problems
+- **Do not review non-default keymaps** — flag their presence and defer to a QMK Collaborator
+- **Do not review `<keyboard>.c` content in detail** — flag its presence and defer to a QMK Collaborator
+
+This is meant as a **first-pass review** to catch common issues before human review. Complex architectural decisions, code quality, and subjective assessments still require human QMK Collaborator review.

.github/workflows/api.yml

@@ -25,7 +25,7 @@ jobs:
     if: github.repository == 'qmk/qmk_firmware'
 
     steps:
-    - uses: actions/checkout@v5
+    - uses: actions/checkout@v7
       with:
         fetch-depth: 1
         persist-credentials: false

.github/workflows/auto_approve.yml

@@ -4,7 +4,7 @@ permissions: {}
 
 on:
   schedule:
-    - cron: "*/5 * * * *"
+    - cron: "*/30 * * * *"
 
 jobs:
   automatic_approve:

.github/workflows/auto_tag.yml

@@ -28,7 +28,7 @@ jobs:
     if: github.repository == 'qmk/qmk_firmware'
 
     steps:
-    - uses: actions/checkout@v5
+    - uses: actions/checkout@v7
       with:
         fetch-depth: 0
 

.github/workflows/bootstrap_testing.yml

@@ -0,0 +1,289 @@
+name: Bootstrap Script Testing
+
+on:
+  push:
+    branches: [master, develop, xap]
+    paths:
+    - 'util/env-bootstrap.sh'
+    - '.github/workflows/bootstrap_testing.yml'
+  pull_request:
+    paths:
+    - 'util/env-bootstrap.sh'
+    - '.github/workflows/bootstrap_testing.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  prep:
+    runs-on: ubuntu-latest
+
+    outputs:
+      any_changed: ${{ steps.file_changes.outputs.any_changed }}
+
+    steps:
+    - name: Get changed files
+      id: file_changes
+      if: ${{ github.event_name == 'pull_request' }}
+      uses: tj-actions/changed-files@v47
+      with:
+        use_rest_api: true
+        files: |
+          util/env-bootstrap.sh
+          .github/workflows/bootstrap_testing.yml
+
+  bootstrap-test-linux:
+    name: Bootstrap (Linux)
+
+    needs: prep
+    if: ${{ github.event_name != 'pull_request' || needs.prep.outputs.any_changed == 'true' }}
+
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        distribution:
+          # Ubuntu/Debian based
+          - debian:11
+          - debian:12
+          - debian:13
+          - ubuntu:22.04
+          - ubuntu:24.04
+          - ubuntu:26.04
+
+          # RHEL/CentOS/Fedora based
+          - fedora:42
+          - fedora:43
+          - fedora:44
+          - rockylinux:8
+          - rockylinux:9
+          - rockylinux/rockylinux:10
+          - almalinux:8
+          - almalinux:9
+          - almalinux:10
+
+          # OpenSUSE based (we skip Tumbleweed as it has issues with package mirrors regularly being out of date)
+          - opensuse/leap:latest
+
+          # Gentoo-based
+          - gentoo/stage3:latest
+
+          # Arch based
+          - archlinux:latest
+          - cachyos/cachyos:latest
+          - manjarolinux/base:latest
+
+    container:
+      image: ${{ matrix.distribution }}
+      options: --privileged
+
+    steps:
+      - name: Install base dependencies
+        run: |
+          # Attempt to run the package installation up to 10 times to mitigate transient network issues
+          for n in $(seq 1 10); do
+            {
+              echo "Attempt #$n of 10 to install base dependencies:"
+              case "${{ matrix.distribution }}" in
+                *ubuntu*|*debian*)
+                  apt-get update
+                  apt-get install -y sudo git passwd
+                  ;;
+                *fedora*|*rockylinux*|*almalinux*)
+                  dnf install -y sudo git passwd findutils  # findutils=xargs
+                  ;;
+                *suse*)
+                  zypper --non-interactive refresh
+                  zypper --non-interactive install sudo git shadow findutils tar  # findutils=xargs
+                  ;;
+                *gentoo*)
+                  emerge-webrsync
+                  emerge --noreplace --ask=n sudo dev-vcs/git shadow findutils  # findutils=xargs
+                  ;;
+                *archlinux*|*cachyos*|*manjaro*)
+                  pacman -Syu --noconfirm
+                  pacman -S --noconfirm sudo git
+                  ;;
+              esac
+            } && break || sleep 10
+          done
+
+          # Fix PAM configuration for sudo in containers
+          # Fix /etc/shadow permissions - common issue in container environments
+          chmod 640 /etc/shadow || chmod 400 /etc/shadow || true
+
+          # Disable problematic PAM modules that commonly fail in RHEL-like containers
+          sed -i 's/^session.*pam_systemd.so/#&/' /etc/pam.d/sudo || true
+          sed -i 's/^session.*pam_loginuid.so/#&/' /etc/pam.d/sudo || true
+
+          # Ensure proper sudoers configuration
+          echo 'Defaults !requiretty' >> /etc/sudoers
+          echo 'Defaults secure_path="/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"' >> /etc/sudoers
+
+      - name: Checkout repository
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 1
+          submodules: recursive
+          path: qmk_firmware
+
+      - name: Create test user
+        run: |
+          # Create a test user for the bootstrap script
+          useradd -m -s /bin/bash -U testuser
+          echo 'testuser:testpassword' | chpasswd || true
+          
+          # Configure passwordless sudo
+          echo "root ALL=(ALL) NOPASSWD:ALL" >> /etc/sudoers  # some distros complain about root not being in sudoers
+          echo "testuser ALL=(ALL) NOPASSWD:ALL" >> /etc/sudoers
+          
+          # Test sudo functionality
+          sudo -u testuser whoami || echo "Sudo test failed, but continuing..."
+
+      - name: Move QMK repository to test user home
+        run: |
+          # Add upstream remote to the cloned repository so `qmk doctor` doesn't flag a warning
+          git -C qmk_firmware remote add upstream https://github.com/qmk/qmk_firmware.git
+          # Move the QMK repository to the test user's home directory
+          mv qmk_firmware /home/testuser/qmk_firmware
+          chown -R testuser:testuser /home/testuser/qmk_firmware
+
+      - name: Run bootstrap script
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          # Ensure the bootstrap script can access sudo
+          sudo -u testuser --preserve-env=GITHUB_TOKEN bash -c "
+            export CONFIRM=1
+            export PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
+            cd /home/testuser
+            bash /home/testuser/qmk_firmware/util/env-bootstrap.sh
+          "
+
+      - name: Install dependencies
+        run: |
+          sudo -u testuser bash -c "
+            /home/testuser/.local/share/uv/tools/qmk/bin/python -m pip install -r /home/testuser/qmk_firmware/requirements.txt
+          "
+
+      - name: Test QMK CLI
+        run: |
+          sudo -u testuser bash -c "
+            export PATH=/home/testuser/.local/bin:\$PATH
+            cd /home/testuser
+            qmk setup -y -H /home/testuser/qmk_firmware  # setup implies doctor, no need to run it separately
+            cd /home/testuser/qmk_firmware
+            qmk mass-compile -j $(nproc) -e DUMP_CI_METADATA=yes -f 'keyboard_name==*onekey*' -km reset -p || touch .failed  # Compile a bunch of different platforms
+          "
+          
+          cd /home/testuser/qmk_firmware
+          ./util/ci/generate_failure_markdown.sh > $GITHUB_STEP_SUMMARY || true
+          [ ! -e .failed ] || exit 1
+
+  bootstrap-test-macos:
+    name: Bootstrap (macOS)
+
+    needs: prep
+    if: ${{ github.event_name != 'pull_request' || needs.prep.outputs.any_changed == 'true' }}
+
+    strategy:
+      fail-fast: false
+      matrix:
+        os:
+          - macos-14        # Apple Silicon ARM64
+          - macos-15        # Apple Silicon ARM64
+          - macos-15-intel  # Intel x64
+          - macos-26        # Apple Silicon ARM64
+
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 1
+          submodules: recursive
+
+      - name: Run bootstrap script
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          # Add upstream remote to the cloned repository so `qmk doctor` doesn't flag a warning
+          git remote add upstream https://github.com/qmk/qmk_firmware.git
+          # Run the bootstrap script
+          export CONFIRM=1
+          sh ./util/env-bootstrap.sh
+
+      - name: Install dependencies
+        run: |
+          $HOME/.local/share/uv/tools/qmk/bin/python -m pip install -r requirements.txt
+
+      - name: Test QMK CLI
+        run: |
+          # Add QMK CLI to PATH (bootstrap script installs it to ~/.local/bin on macOS)
+          export PATH="$HOME/.local/bin:$PATH"
+          qmk setup -y -H .  # setup implies doctor, no need to run it separately
+          qmk mass-compile -j $(sysctl -n hw.ncpu) -e DUMP_CI_METADATA=yes -f 'keyboard_name==*onekey*' -km reset || touch .failed  # Compile a bunch of different platforms
+          
+          ./util/ci/generate_failure_markdown.sh > $GITHUB_STEP_SUMMARY || true
+          [ ! -e .failed ] || exit 1
+
+  bootstrap-test-windows:
+    name: Bootstrap (Windows)
+
+    needs: prep
+    if: ${{ github.event_name != 'pull_request' || needs.prep.outputs.any_changed == 'true' }}
+
+    strategy:
+      fail-fast: false
+      matrix:
+        msys-variant:
+          - mingw64
+          - clang64
+          - ucrt64
+
+    runs-on: windows-latest
+    defaults:
+      run:
+        shell: msys2 {0}
+
+    steps:
+      - name: Install MSYS2
+        uses: msys2/setup-msys2@v2
+        with:
+          msystem: ${{ matrix.msys-variant }}
+          pacboy: >-
+            git:
+
+      - name: Checkout repository
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 1
+          submodules: recursive
+
+      - name: Run bootstrap script
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          # Add upstream remote to the cloned repository so `qmk doctor` doesn't flag a warning
+          git remote add upstream https://github.com/qmk/qmk_firmware.git
+          # Run the bootstrap script
+          export CONFIRM=1
+          sh ./util/env-bootstrap.sh
+
+      - name: Install dependencies
+        run: |
+          /opt/uv/tools/qmk/Scripts/python -m pip install -r requirements.txt
+
+      - name: Test QMK CLI
+        run: |
+          # Add QMK CLI to PATH (bootstrap script installs it to /opt/uv/tools/bin on Windows MSYS2)
+          export PATH="/opt/uv/tools/bin:$PATH"
+          qmk setup -y -H .  # setup implies doctor, no need to run it separately
+          qmk mass-compile -j $(nproc) -e DUMP_CI_METADATA=yes -f 'keyboard_name==*onekey*' -km reset || touch .failed  # Compile a bunch of different platforms
+          
+          ./util/ci/generate_failure_markdown.sh > $GITHUB_STEP_SUMMARY || true
+          [ ! -e .failed ] || exit 1
+

.github/workflows/ci_build_major_branch.yml

@@ -32,29 +32,36 @@ jobs:
     container: ghcr.io/qmk/qmk_cli
 
     outputs:
+      keymaps: ${{ steps.generate_slice_length.outputs.keymaps }}
       slice_length: ${{ steps.generate_slice_length.outputs.slice_length }}
 
     steps:
-      - name: Install prerequisites
-        run: |
-          apt-get update
-          apt-get install -y jq
-
       - name: Disable safe.directory check
         run: |
           git config --global --add safe.directory '*'
 
       - name: Checkout QMK Firmware
-        uses: actions/checkout@v5
+        uses: actions/checkout@v7
+
+      - name: Install dependencies
+        run: pip3 install -r requirements-dev.txt
 
       - name: Determine concurrency
         id: generate_slice_length
+        shell: 'bash {0}'
         run: |
-          target_count=$( {
-            qmk find -km default 2>/dev/null
-            qmk find -km xap 2>/dev/null
-          } | sort | uniq | wc -l)
+          targets=()
+          target_count=0
+          for target in "default" "xap"; do
+              count=$(qmk find -km $target 2>/dev/null | wc -l)
+              if [ $count -gt 0 ]; then
+                  target_count=$(($target_count + $count))
+                  targets+=($target)
+              fi
+          done
+          keymaps=$(jq -c -n '$ARGS.positional' --args "${targets[@]}")
           slice_length=$((target_count / ($CONCURRENT_JOBS - 1))) # Err on the side of caution
+          echo "keymaps=$keymaps" >> $GITHUB_OUTPUT
           echo "slice_length=$slice_length" >> $GITHUB_OUTPUT
 
   build_targets:
@@ -63,7 +70,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        keymap: [default, xap]
+        keymap: ${{ fromJson(needs.determine_concurrency.outputs.keymaps) }}
     uses: ./.github/workflows/ci_build_major_branch_keymap.yml
     with:
       branch: ${{ inputs.branch || github.ref_name }}
@@ -82,12 +89,12 @@ jobs:
           git config --global --add safe.directory '*'
 
       - name: Checkout QMK Firmware
-        uses: actions/checkout@v5
+        uses: actions/checkout@v7
         with:
           fetch-depth: 0
 
       - name: Download firmwares
-        uses: actions/download-artifact@v6
+        uses: actions/download-artifact@v8
         with:
           pattern: firmware-*
           path: .
@@ -125,14 +132,7 @@ jobs:
           SOURCE_DIR: .
           DEST_DIR: ${{ inputs.branch || github.ref_name }}/latest
 
-      - name: Check if failure marker file exists
-        id: check_failure_marker
-        uses: andstor/file-existence-action@v3
-        with:
-          files: ./.failed
-
       - name: Fail build if needed
-        if: steps.check_failure_marker.outputs.files_exists == 'true'
         run: |
           # Exit with failure if the compilation stage failed
-          exit 1
+          [ ! -e .failed ] || exit 1

.github/workflows/ci_build_major_branch_keymap.yml

@@ -27,30 +27,29 @@ jobs:
       targets: ${{ steps.generate_targets.outputs.targets }}
 
     steps:
-      - name: Install prerequisites
-        run: |
-          apt-get update
-          apt-get install -y jq
-
       - name: Disable safe.directory check
         run: |
           git config --global --add safe.directory '*'
 
       - name: Checkout QMK Firmware
-        uses: actions/checkout@v5
+        uses: actions/checkout@v7
+
+      - name: Install dependencies
+        run: pip3 install -r requirements-dev.txt
 
       - name: Generate build targets
+        shell: 'bash {0}'
         id: generate_targets
         run: |
           { # Intentionally use `shuf` here so that we share manufacturers across all build groups -- some have a lot of ARM-based boards which inherently take longer
             counter=0
             echo -n '{'
-            qmk find -km ${{ inputs.keymap }} 2>/dev/null | sort | uniq | shuf | xargs -L${{ inputs.slice_length }} | while IFS=$'\n' read target ; do
+            qmk find -km ${{ inputs.keymap }} 2>/dev/null | sort | uniq | shuf --random-source=<(openssl enc -aes-256-ctr -pass pass:qmk -nosalt </dev/zero 2>/dev/null) | xargs -L${{ inputs.slice_length }} | while IFS=$'\n' read target ; do
                 if [ $counter -gt 0 ]; then
                     echo -n ','
                 fi
                 counter=$((counter+1))
-                printf "\"group %02d\":{" $counter
+                printf "\"group-%02d\":{" $counter
                 echo -n '"targets":"'
                 echo $target | tr ' ' '\n' | sort | uniq | xargs echo -n
                 echo -n '"}'
@@ -62,7 +61,7 @@ jobs:
           echo "targets=$(jq -c 'keys' targets.json)" >> $GITHUB_OUTPUT
 
       - name: Upload targets json
-        uses: actions/upload-artifact@v5
+        uses: actions/upload-artifact@v7
         with:
           name: targets-${{ inputs.keymap }}
           path: targets.json
@@ -74,45 +73,76 @@ jobs:
     container: ghcr.io/qmk/qmk_cli
     continue-on-error: true
 
+    env:
+      CCACHE_CONFIGPATH: ~/.cache
+
     strategy:
       matrix:
         target: ${{ fromJson(needs.generate_targets.outputs.targets) }}
 
     steps:
-      - name: Install prerequisites
-        run: |
-          apt-get update
-          apt-get install -y jq
-
       - name: Disable safe.directory check
         run: |
           git config --global --add safe.directory '*'
 
       - name: Checkout QMK Firmware
-        uses: actions/checkout@v5
+        uses: actions/checkout@v7
+        with:
+          submodules: recursive
+
+      - name: Install dependencies
+        run: pip3 install -r requirements-dev.txt
 
       - name: Get target definitions
-        uses: actions/download-artifact@v6
+        uses: actions/download-artifact@v8
         with:
           name: targets-${{ inputs.keymap }}
           path: .
 
-      - name: Deploy submodules
-        run: |
-          qmk git-submodule -f
-
       - name: Dump targets
         run: |
           jq -r '.["${{ matrix.target }}"].targets' targets.json | tr ' ' '\n' | sort
 
+      - name: Restore Cache
+        id: cache
+        uses: actions/cache/restore@v6
+        with:
+          path: ${{ env.CCACHE_CONFIGPATH }}
+          key: compile-${{ inputs.keymap }}-${{ matrix.target }}
+
       - name: Build targets
         continue-on-error: true
         run: |
-          export NCPUS=$(( $(nproc 2>/dev/null || sysctl -n hw.ncpu 2>/dev/null || getconf _NPROCESSORS_ONLN 2>/dev/null) -1 ))
-          qmk mass-compile -t -j $NCPUS -e DUMP_CI_METADATA=yes $(jq -r '.["${{ matrix.target }}"].targets' targets.json) || touch .failed
+          targets=$(jq -r '.["${{ matrix.target }}"].targets' targets.json | tr ' ' '\n' | sort)
+          if [ -z "${targets}" ]; then
+            echo "Zero build targets detected"
+            exit 0
+          fi
+          qmk mass-compile -t -j $(nproc) -e DUMP_CI_METADATA=yes -e USE_CCACHE=yes $targets || touch .failed
+
+      - name: Dump ccache stats
+        run: |
+          ccache -s
+
+      # Delete the old cache on hit to emulate a cache update. See https://github.com/actions/cache/issues/342.
+      - name: Delete old cache
+        env:
+          GH_TOKEN: ${{ github.token }}
+        if: steps.cache.outputs.cache-hit
+        run: |
+          count=$(gh cache list --ref ${{ github.ref }} --key ${{ steps.cache.outputs.cache-primary-key }} --json id | jq length)
+          if [ $count -gt 0 ]; then
+            gh cache delete --ref ${{ github.ref }} ${{ steps.cache.outputs.cache-primary-key }}
+          fi
+
+      - name: Save Cache
+        uses: actions/cache/save@v6
+        with:
+          path: ${{ env.CCACHE_CONFIGPATH }}
+          key: compile-${{ inputs.keymap }}-${{ matrix.target }}
 
       - name: Upload binaries
-        uses: actions/upload-artifact@v5
+        uses: actions/upload-artifact@v7
         with:
           name: firmware-${{ inputs.keymap }}-${{ matrix.target }}
           if-no-files-found: ignore
@@ -136,17 +166,17 @@ jobs:
 
     steps:
       - name: Checkout QMK Firmware
-        uses: actions/checkout@v5
+        uses: actions/checkout@v7
 
       - name: Download firmwares
-        uses: actions/download-artifact@v6
+        uses: actions/download-artifact@v8
         with:
           pattern: firmware-${{ inputs.keymap }}-*
           path: .
           merge-multiple: true
 
       - name: Upload all firmwares
-        uses: actions/upload-artifact@v5
+        uses: actions/upload-artifact@v7
         with:
           name: firmware-${{ inputs.keymap }}
           if-no-files-found: ignore
@@ -165,7 +195,7 @@ jobs:
           truncate --size='<960K' $GITHUB_STEP_SUMMARY || true
 
       - name: Delete temporary build artifacts
-        uses: geekyeggo/delete-artifact@v5
+        uses: geekyeggo/delete-artifact@v6
         with:
           name: |
             firmware-${{ inputs.keymap }}-*

.github/workflows/cli.yml

@@ -24,11 +24,12 @@ jobs:
     - name: Disable safe.directory check
       run : git config --global --add safe.directory '*'
 
-    - uses: actions/checkout@v5
+    - uses: actions/checkout@v7
       with:
         submodules: recursive
 
     - name: Install dependencies
       run: pip3 install -r requirements-dev.txt
+
     - name: Run tests
       run: qmk pytest

.github/workflows/develop_docs.yml

@@ -0,0 +1,34 @@
+name: Generate Develop Docs
+
+permissions:
+  contents: write
+
+on:
+  push:
+    branches:
+    - develop
+    paths:
+    - 'builddefs/docsgen/**'
+    - 'tmk_core/**'
+    - 'quantum/**'
+    - 'platforms/**'
+    - 'docs/**'
+    - '.github/workflows/docs.yml'
+
+jobs:
+  generate:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Deploy Develop
+      if: ${{ github.repository == 'qmk/qmk_firmware' }}
+      uses: actions/github-script@v9
+      with:
+        github-token: ${{ secrets.QMK_BOT_TOKEN }}
+        script: |
+          const result = await github.rest.actions.createWorkflowDispatch({
+            owner: 'qmk',
+            repo: 'qmk_docs_devel',
+            workflow_id: 'develop.yml',
+            ref: 'main',
+          })

.github/workflows/develop_update.yml

@@ -15,7 +15,7 @@ jobs:
     if: github.repository == 'qmk/qmk_firmware'
 
     steps:
-    - uses: actions/checkout@v5
+    - uses: actions/checkout@v7
       with:
         token: ${{ secrets.QMK_BOT_TOKEN }}
         fetch-depth: 0

.github/workflows/docs.yml

@@ -30,14 +30,15 @@ jobs:
     container: ghcr.io/qmk/qmk_cli
 
     steps:
-    - uses: actions/checkout@v5
+    - uses: actions/checkout@v7
       with:
         fetch-depth: 1
 
     - name: Install dependencies
+      run: pip3 install -r requirements-dev.txt
+
+    - name: Install nvm
       run: |
-        apt-get update && apt-get install -y rsync doxygen
-        # install nvm
         touch $HOME/.bashrc
         wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
 
@@ -56,7 +57,7 @@ jobs:
 
     - name: Deploy
       if: ${{ github.event_name == 'push' && github.repository == 'qmk/qmk_firmware' }}
-      uses: JamesIves/github-pages-deploy-action@v4.7.4
+      uses: JamesIves/github-pages-deploy-action@v4.8.0
       with:
           token: ${{ secrets.GITHUB_TOKEN }}
           branch: gh-pages

.github/workflows/feature_branch_update.yml

@@ -21,7 +21,7 @@ jobs:
         - riot
 
     steps:
-    - uses: actions/checkout@v5
+    - uses: actions/checkout@v7
       with:
         token: ${{ secrets.QMK_BOT_TOKEN }}
         fetch-depth: 0

.github/workflows/format.yml

@@ -26,7 +26,7 @@ jobs:
     - name: Disable safe.directory check
       run : git config --global --add safe.directory '*'
 
-    - uses: actions/checkout@v5
+    - uses: actions/checkout@v7
       with:
         fetch-depth: 0
 

.github/workflows/format_push.yml

@@ -19,7 +19,7 @@ jobs:
     - name: Disable safe.directory check
       run : git config --global --add safe.directory '*'
 
-    - uses: actions/checkout@v5
+    - uses: actions/checkout@v7
       with:
         fetch-depth: 0
 
@@ -47,7 +47,7 @@ jobs:
         git config user.email 'hello@qmk.fm'
 
     - name: Create Pull Request
-      uses: peter-evans/create-pull-request@v7
+      uses: peter-evans/create-pull-request@v8
       if: ${{ github.repository == 'qmk/qmk_firmware'}}
       with:
         token: ${{ secrets.QMK_BOT_TOKEN }}

.github/workflows/lint.yml

@@ -18,7 +18,7 @@ jobs:
     - name: Disable safe.directory check
       run : git config --global --add safe.directory '*'
 
-    - uses: actions/checkout@v5
+    - uses: actions/checkout@v7
       with:
         fetch-depth: 0
 
@@ -31,7 +31,7 @@ jobs:
       with:
         use_rest_api: true
 
-    - name: Print info
+    - name: Print git info
       run: |
         git rev-parse --short HEAD
         echo ${{ github.event.pull_request.base.sha }}
@@ -57,7 +57,7 @@ jobs:
           if [[ $KEYMAP_ONLY -gt 0 ]]; then
             echo "linting ${KB}"
 
-            qmk lint --keyboard ${KB} && qmk info -l --keyboard ${KB}
+            qmk lint --strict --keyboard ${KB} && qmk info -l --keyboard ${KB}
             exit_code=$(($exit_code + $?))
           fi
         done
@@ -78,10 +78,21 @@ jobs:
         fi
         exit $exit_code
 
-    - name: Verify keyboard aliases
+    - name: Reset git repo
       if: always()
       shell: 'bash {0}'
       run: |
         git reset --hard
         git clean -xfd
+
+    - name: Verify keyboard targets
+      if: always()
+      shell: 'bash {0}'
+      run: |
+        qmk ci-validate-keyboard-targets
+
+    - name: Verify keyboard aliases
+      if: always()
+      shell: 'bash {0}'
+      run: |
         qmk ci-validate-aliases

.github/workflows/regen.yml

@@ -8,6 +8,9 @@ on:
     paths:
     - 'data/constants/**'
     - 'lib/python/**'
+    - 'quantum/rgblight/rgblight_breathe_table.h'
+    - 'quantum/keycodes.h'
+    - 'quantum/keymap_extras/**'
 
 jobs:
   regen:
@@ -19,7 +22,10 @@ jobs:
     - name: Disable safe.directory check
       run : git config --global --add safe.directory '*'
 
-    - uses: actions/checkout@v5
+    - uses: actions/checkout@v7
+
+    - name: Install dependencies
+      run: pip3 install -r requirements-dev.txt
 
     - name: Run qmk generators
       run: |

.github/workflows/regen_push.yml

@@ -19,7 +19,10 @@ jobs:
     - name: Disable safe.directory check
       run : git config --global --add safe.directory '*'
 
-    - uses: actions/checkout@v5
+    - uses: actions/checkout@v7
+
+    - name: Install dependencies
+      run: pip3 install -r requirements-dev.txt
 
     - name: Run qmk generators
       run: |
@@ -34,7 +37,7 @@ jobs:
         git config user.email 'hello@qmk.fm'
 
     - name: Create Pull Request
-      uses: peter-evans/create-pull-request@v7
+      uses: peter-evans/create-pull-request@v8
       if: ${{ github.repository == 'qmk/qmk_firmware'}}
       with:
         token: ${{ secrets.QMK_BOT_TOKEN }}

.github/workflows/unit_test.yml

@@ -11,6 +11,7 @@ on:
   pull_request:
     paths:
     - 'builddefs/**'
+    - '!builddefs/docsgen/**'
     - 'quantum/**'
     - 'platforms/**'
     - 'tmk_core/**'
@@ -26,10 +27,12 @@ jobs:
     container: ghcr.io/qmk/qmk_cli
 
     steps:
-    - uses: actions/checkout@v5
+    - uses: actions/checkout@v7
       with:
         submodules: recursive
+
     - name: Install dependencies
       run: pip3 install -r requirements-dev.txt
+
     - name: Run tests
-      run: qmk test-c
+      run: qmk test-c -j $(nproc)

.gitignore

@@ -65,6 +65,8 @@ cmake-build-debug
 CMakeLists.txt
 *.pdf
 *.zip
+.env
+.envrc
 
 # Let these ones be user specific, since we have so many different configurations
 *.code-workspace

Makefile

@@ -1,4 +1,4 @@
-ifndef VERBOSE
+ifneq ($(VERBOSE),true)
 .SILENT:
 endif
 
@@ -38,14 +38,17 @@ $(info QMK Firmware $(QMK_VERSION))
 endif
 endif
 
-# Try to determine userspace from qmk config, if set.
-ifeq ($(QMK_USERSPACE),)
-    QMK_USERSPACE = $(shell qmk config -ro user.overlay_dir | cut -d= -f2 | sed -e 's@^None$$@@g')
-endif
-
 # Determine which qmk cli to use
 QMK_BIN := qmk
 
+# Try to determine userspace from qmk config, if set. Handle direct query on qmk_cli>=1.1.7
+# falling back to legacy method of only supporting user.overlay_dir config
+# sort is used to buffer 'qmk env' output and avoid BrokenPipeError errors
+export override QMK_USERSPACE := $(shell \
+    $(QMK_BIN) env | sort | grep -q QMK_USERSPACE \
+        && $(QMK_BIN) env QMK_USERSPACE \
+        || $(QMK_BIN) config -ro user.overlay_dir | cut -d= -f2 | sed -e 's@^None$$@@g')
+
 # avoid 'Entering|Leaving directory' messages
 MAKEFLAGS += --no-print-directory
 
@@ -115,7 +118,7 @@ endef
 TRY_TO_MATCH_RULE_FROM_LIST = $(eval $(call TRY_TO_MATCH_RULE_FROM_LIST_HELPER,$1))$(RULE_FOUND)
 
 # As TRY_TO_MATCH_RULE_FROM_LIST_HELPER, but with additional
-# resolution of keyboard_aliases.hjson for provided rule 
+# resolution of keyboard_aliases.hjson for provided rule
 define TRY_TO_MATCH_RULE_FROM_LIST_HELPER_KB
     # Split on ":", padding with empty strings to avoid indexing issues
     TOKEN1:=$$(shell python3 -c "import sys; print((sys.argv[1].split(':',1)+[''])[0])" $$(RULE))
@@ -190,41 +193,9 @@ endef
 # Parses a rule in the format <keymap>:<target>
 # the keyboard is already known when entering this function
 define PARSE_KEYBOARD
-    # If we want to compile the default subproject, then we need to
-    # include the correct makefile to determine the actual name of it
     CURRENT_KB := $1
 
-    # 5/4/3/2/1
-    KEYBOARD_FOLDER_PATH_1 := $$(CURRENT_KB)
-    KEYBOARD_FOLDER_PATH_2 := $$(patsubst %/,%,$$(dir $$(KEYBOARD_FOLDER_PATH_1)))
-    KEYBOARD_FOLDER_PATH_3 := $$(patsubst %/,%,$$(dir $$(KEYBOARD_FOLDER_PATH_2)))
-    KEYBOARD_FOLDER_PATH_4 := $$(patsubst %/,%,$$(dir $$(KEYBOARD_FOLDER_PATH_3)))
-    KEYBOARD_FOLDER_PATH_5 := $$(patsubst %/,%,$$(dir $$(KEYBOARD_FOLDER_PATH_4)))
-
-    KEYMAPS :=
-    # get a list of all keymaps
-    KEYMAPS += $$(notdir $$(patsubst %/.,%,$$(wildcard $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_PATH_1)/keymaps/*/.)))
-    KEYMAPS += $$(notdir $$(patsubst %/.,%,$$(wildcard $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_PATH_2)/keymaps/*/.)))
-    KEYMAPS += $$(notdir $$(patsubst %/.,%,$$(wildcard $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_PATH_3)/keymaps/*/.)))
-    KEYMAPS += $$(notdir $$(patsubst %/.,%,$$(wildcard $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_PATH_4)/keymaps/*/.)))
-    KEYMAPS += $$(notdir $$(patsubst %/.,%,$$(wildcard $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_PATH_5)/keymaps/*/.)))
-
-    ifneq ($(QMK_USERSPACE),)
-        KEYMAPS += $$(notdir $$(patsubst %/.,%,$$(wildcard $(QMK_USERSPACE)/keyboards/$$(KEYBOARD_FOLDER_PATH_1)/keymaps/*/.)))
-        KEYMAPS += $$(notdir $$(patsubst %/.,%,$$(wildcard $(QMK_USERSPACE)/keyboards/$$(KEYBOARD_FOLDER_PATH_2)/keymaps/*/.)))
-        KEYMAPS += $$(notdir $$(patsubst %/.,%,$$(wildcard $(QMK_USERSPACE)/keyboards/$$(KEYBOARD_FOLDER_PATH_3)/keymaps/*/.)))
-        KEYMAPS += $$(notdir $$(patsubst %/.,%,$$(wildcard $(QMK_USERSPACE)/keyboards/$$(KEYBOARD_FOLDER_PATH_4)/keymaps/*/.)))
-        KEYMAPS += $$(notdir $$(patsubst %/.,%,$$(wildcard $(QMK_USERSPACE)/keyboards/$$(KEYBOARD_FOLDER_PATH_5)/keymaps/*/.)))
-    endif
-
-    KEYBOARD_LAYOUTS := $(shell $(QMK_BIN) list-layouts --keyboard $1)
-    LAYOUT_KEYMAPS :=
-    $$(foreach LAYOUT,$$(KEYBOARD_LAYOUTS),$$(eval LAYOUT_KEYMAPS += $$(notdir $$(patsubst %/.,%,$$(wildcard $(ROOT_DIR)/layouts/*/$$(LAYOUT)/*/.)))))
-    ifneq ($(QMK_USERSPACE),)
-        $$(foreach LAYOUT,$$(KEYBOARD_LAYOUTS),$$(eval LAYOUT_KEYMAPS += $$(notdir $$(patsubst %/.,%,$$(wildcard $(QMK_USERSPACE)/layouts/$$(LAYOUT)/*/.)))))
-    endif
-
-    KEYMAPS := $$(sort $$(KEYMAPS) $$(LAYOUT_KEYMAPS))
+    KEYMAPS := $(shell $(QMK_BIN) list-keymaps --keyboard $1)
 
     # if the rule after removing the start of it is empty (we haven't specified a kemap or target)
     # compile all the keymaps
@@ -329,6 +300,7 @@ endef
 define BUILD_TEST
     TEST_PATH := $1
     TEST_NAME := $$(notdir $$(TEST_PATH))
+    TEST_ID := $$(patsubst ./tests/%,%,$$(TEST_PATH))
     TEST_FULL_NAME := $$(subst /,_,$$(patsubst $$(ROOT_DIR)tests/%,%,$$(TEST_PATH)))
     MAKE_TARGET := $2
     COMMAND := $1
@@ -342,7 +314,7 @@ define BUILD_TEST
         TEST_MSG := $$(MSG_TEST)
         $$(TEST_FULL_NAME)_COMMAND := \
             printf "$$(TEST_MSG)\n"; \
-            $$(TEST_EXECUTABLE); \
+            $$(TEST_EXECUTABLE) --gtest_color=$$(COLOR); \
             if [ $$$$? -gt 0 ]; \
                 then error_occurred=1; \
             fi; \
@@ -480,16 +452,17 @@ distclean_userspace: clean
 endif
 
 # Extra targets for formatting and/or pytest, running within the qmk/qmk_cli container to match GHA.
-CONTAINER_PREAMBLE := export HOME="/tmp"; export PATH="/tmp/.local/bin:\$$PATH"; python3 -m pip install --upgrade pip; python3 -m pip install -r requirements-dev.txt
-
 .PHONY: format-core
 format-core:
-	RUNTIME=docker ./util/docker_cmd.sh bash -lic "$(CONTAINER_PREAMBLE); qmk format-c --core-only -a && qmk format-python -a"
+	RUNTIME=docker ./util/docker_cmd.sh qmk format-c --core-only -a
+	RUNTIME=docker ./util/docker_cmd.sh qmk format-python -a
 
 .PHONY: pytest
 pytest:
-	RUNTIME=docker ./util/docker_cmd.sh bash -lic "$(CONTAINER_PREAMBLE); qmk pytest"
+	RUNTIME=docker ./util/docker_cmd.sh qmk pytest
 
 .PHONY: format-and-pytest
 format-and-pytest:
-	RUNTIME=docker ./util/docker_cmd.sh bash -lic "$(CONTAINER_PREAMBLE); qmk format-c --core-only -a && qmk format-python -a && qmk pytest"
+	RUNTIME=docker ./util/docker_cmd.sh qmk format-c --core-only -a
+	RUNTIME=docker ./util/docker_cmd.sh qmk format-python -a
+	RUNTIME=docker ./util/docker_cmd.sh qmk pytest