Merge branch 'qmk:master' into master

.github/workflows/ci_builds.yml

@@ -4,10 +4,9 @@ permissions:
   contents: read
 
 on:
-  push:
-    branches:
-    - master
-    - develop
+  workflow_dispatch:
+  schedule:
+    - cron: '0 0,12 * * *'
 
 jobs:
   ci_builds:
@@ -18,7 +17,9 @@ jobs:
     if: github.repository == 'qmk/qmk_firmware'
 
     strategy:
+      fail-fast: false
       matrix:
+        branch: [master, develop]
         keymap: [default, via]
 
     container: qmkfm/qmk_cli
@@ -30,19 +31,30 @@ jobs:
     - uses: actions/checkout@v3
       with:
         submodules: recursive
+        ref: ${{ matrix.branch }}
 
     - name: Install dependencies
       run: pip3 install -r requirements.txt
 
     - name: Run `qmk mass-compile` (keymap ${{ matrix.keymap }})
-      run: qmk mass-compile -j $(nproc 2>/dev/null || sysctl -n hw.ncpu 2>/dev/null || getconf _NPROCESSORS_ONLN 2>/dev/null) -km ${{ matrix.keymap }}
-
-    - name: 'Upload binaries'
+      run: |
+        export NCPUS=$(nproc 2>/dev/null || sysctl -n hw.ncpu 2>/dev/null || getconf _NPROCESSORS_ONLN 2>/dev/null)
+        qmk mass-compile -t -j $NCPUS -km ${{ matrix.keymap }} -e DUMP_CI_METADATA=yes || touch .failed
+        # Generate the step summary markdown
+        ./util/ci/generate_failure_markdown.sh > $GITHUB_STEP_SUMMARY || true
+        # Truncate to a maximum of 1MB to deal with GitHub workflow limit
+        truncate --size='<960K' $GITHUB_STEP_SUMMARY || true
+        # Exit with failure if the compilation stage failed
+        [ ! -f .failed ] || exit 1
+
+    - name: 'Upload artifacts'
       uses: actions/upload-artifact@v3
+      if: always()
       with:
-        name: binaries-${{ matrix.keymap }}
+        name: artifacts-${{ matrix.branch }}-${{ matrix.keymap }}
         if-no-files-found: ignore
         path: |
           *.bin
           *.hex
           *.uf2
+          .build/failed.*

.github/workflows/stale.yml

@@ -13,7 +13,7 @@ jobs:
   stale:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/stale@v7
+      - uses: actions/stale@v8
         with:
           repo-token: ${{ secrets.GITHUB_TOKEN }}
 

builddefs/build_keyboard.mk

@@ -29,6 +29,11 @@ KEYBOARD_FILESAFE := $(subst /,_,$(KEYBOARD))
 TARGET ?= $(KEYBOARD_FILESAFE)_$(KEYMAP)
 KEYBOARD_OUTPUT := $(BUILD_DIR)/obj_$(KEYBOARD_FILESAFE)
 
+ifeq ($(strip $(DUMP_CI_METADATA)),yes)
+    $(info CI Metadata: KEYBOARD=$(KEYBOARD))
+    $(info CI Metadata: KEYMAP=$(KEYMAP))
+endif
+
 # Force expansion
 TARGET := $(TARGET)
 

docs/feature_pointing_device.md

@@ -20,13 +20,13 @@ To use the ADNS 5050 sensor, add this to your `rules.mk`
 POINTING_DEVICE_DRIVER = adns5050
 ```
 
-The ADNS 5050 sensor uses a serial type protocol for communication, and requires an additional light source. 
+The ADNS 5050 sensor uses a serial type protocol for communication, and requires an additional light source.
 
-| Setting             | Description                                                        | Default                    |
-| ------------------- | ------------------------------------------------------------------ | -------------------------- |
-| `ADNS5050_SCLK_PIN` | (Required) The pin connected to the clock pin of the sensor.       | `POINTING_DEVICE_SCLK_PIN` |
-| `ADNS5050_SDIO_PIN` | (Required) The pin connected to the data pin of the sensor.        | `POINTING_DEVICE_SDIO_PIN` |
-| `ADNS5050_CS_PIN`   | (Required) The pin connected to the Chip Select pin of the sensor. | `POINTING_DEVICE_CS_PIN`   |
+| Setting (`config.h`) | Description                                                        | Default                    |
+| -------------------- | ------------------------------------------------------------------ | -------------------------- |
+| `ADNS5050_SCLK_PIN`  | (Required) The pin connected to the clock pin of the sensor.       | `POINTING_DEVICE_SCLK_PIN` |
+| `ADNS5050_SDIO_PIN`  | (Required) The pin connected to the data pin of the sensor.        | `POINTING_DEVICE_SDIO_PIN` |
+| `ADNS5050_CS_PIN`    | (Required) The pin connected to the Chip Select pin of the sensor. | `POINTING_DEVICE_CS_PIN`   |
 
 
 
@@ -40,9 +40,9 @@ To use the ADNS 9800 sensor, add this to your `rules.mk`
 POINTING_DEVICE_DRIVER = adns9800
 ```
 
-The ADNS 9800 is an SPI driven optical sensor, that uses laser output for surface tracking. 
+The ADNS 9800 is an SPI driven optical sensor, that uses laser output for surface tracking.
 
-| Setting                 | Description                                                            | Default                  |
+| Setting (`config.h`)    | Description                                                            | Default                  |
 | ----------------------- | ---------------------------------------------------------------------- | ------------------------ |
 | `ADNS9800_CLOCK_SPEED`  | (Optional) Sets the clock speed that the sensor runs at.               | `2000000`                |
 | `ADNS9800_SPI_LSBFIRST` | (Optional) Sets the Least/Most Significant Byte First setting for SPI. | `false`                  |
@@ -63,7 +63,7 @@ POINTING_DEVICE_DRIVER = analog_joystick
 
 The Analog Joystick is an analog (ADC) driven sensor.  There are a variety of joysticks that you can use for this.
 
-| Setting                           | Description                                                                | Default       |
+| Setting (`config.h`)              | Description                                                                | Default       |
 | --------------------------------- | -------------------------------------------------------------------------- | ------------- |
 | `ANALOG_JOYSTICK_X_AXIS_PIN`      | (Required) The pin used for the vertical/X axis.                           | _not defined_ |
 | `ANALOG_JOYSTICK_Y_AXIS_PIN`      | (Required) The pin used for the horizontal/Y axis.                         | _not defined_ |
@@ -153,7 +153,7 @@ Additionally, `POINTING_DEVICE_GESTURES_CURSOR_GLIDE_ENABLE` is supported in thi
 
 #### Relative mode gestures
 
-| Gesture Setting                        | Description                                                                                                                                                                               | Default       |
+| Gesture Setting (`config.h`)           | Description                                                                                                                                                                               | Default       |
 | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
 | `CIRQUE_PINNACLE_TAP_ENABLE`           | (Optional) Enable tap to "left click". Works on both sides of a split keyboard.                                                                                                           | _not defined_ |
 | `CIRQUE_PINNACLE_SECONDARY_TAP_ENABLE` | (Optional) Tap in upper right corner (half of the finger needs to be outside of the trackpad) of the trackpad will result in "right click". `CIRQUE_PINNACLE_TAP_ENABLE` must be enabled. | _not defined_ |
@@ -172,10 +172,10 @@ POINTING_DEVICE_DRIVER = paw3204
 
 The paw 3204 sensor uses a serial type protocol for communication, and requires an additional light source. 
 
-| Setting            | Description                                                    | Default                    |
-| ------------------ |--------------------------------------------------------------- | -------------------------- |
-| `PAW3204_SCLK_PIN` | (Required) The pin connected to the clock pin of the sensor.   | `POINTING_DEVICE_SCLK_PIN` |
-| `PAW3204_SDIO_PIN` | (Required) The pin connected to the data pin of the sensor.    | `POINTING_DEVICE_SDIO_PIN` |
+| Setting (`config.h`) | Description                                                    | Default                    |
+| -------------------- |--------------------------------------------------------------- | -------------------------- |
+| `PAW3204_SCLK_PIN`   | (Required) The pin connected to the clock pin of the sensor.   | `POINTING_DEVICE_SCLK_PIN` |
+| `PAW3204_SDIO_PIN`   | (Required) The pin connected to the data pin of the sensor.    | `POINTING_DEVICE_SDIO_PIN` |
 
 The CPI range is 400-1600, with supported values of (400, 500, 600, 800, 1000, 1200 and 1600).  Defaults to 1000 CPI.
 
@@ -189,7 +189,7 @@ POINTING_DEVICE_DRIVER = pimoroni_trackball
 
 The Pimoroni Trackball module is a I2C based breakout board with an RGB enable trackball. 
 
-| Setting                              | Description                                                                        | Default |
+| Setting (`config.h`)                 | Description                                                                        | Default |
 | ------------------------------------ | ---------------------------------------------------------------------------------- | ------- |
 | `PIMORONI_TRACKBALL_ADDRESS`         | (Required) Sets the I2C Address for the Pimoroni Trackball.                        | `0x0A`  |
 | `PIMORONI_TRACKBALL_TIMEOUT`         | (Optional) The timeout for i2c communication with the trackball in milliseconds.   | `100`   |
@@ -220,7 +220,7 @@ The CPI range is 50-16000, in increments of 50. Defaults to 2000 CPI.
 Both PMW 3360 and PMW 3389 are SPI driven optical sensors, that use a built in IR LED for surface tracking.
 If you have different CS wiring on each half you can use `PMW33XX_CS_PIN_RIGHT` or `PMW33XX_CS_PINS_RIGHT` in combination with `PMW33XX_CS_PIN` or `PMW33XX_CS_PINS` to configure both sides independently. If `_RIGHT` values aren't provided, they default to be the same as the left ones.
 
-| Setting                      | Description                                                                                 | Default                  |
+| Setting (`config.h`)         | Description                                                                                 | Default                  |
 | ---------------------------- | ------------------------------------------------------------------------------------------- | ------------------------ |
 | `PMW33XX_CS_PIN`             | (Required) Sets the Chip Select pin connected to the sensor.                                | `POINTING_DEVICE_CS_PIN` |
 | `PMW33XX_CS_PINS`            | (Alternative) Sets the Chip Select pins connected to multiple sensors.                      | `{PMW33XX_CS_PIN}`       |

docs/newbs_getting_started.md

@@ -172,6 +172,8 @@ For example, to build a firmware for a Clueboard 66% you would use:
 
     qmk compile -kb clueboard/66/rev3 -km default
 
+?> The keyboard option is the path relative to the keyboard directory, the above example would be found in `qmk_firmware/keyboards/clueboard/66/rev3`. If you're unsure you can view a full list of supported keyboards with `qmk list-keyboards`.
+
 When it is done you should have a lot of output that ends similar to this:
 
 ```

docs/other_vscode.md

@@ -46,16 +46,7 @@ Before starting, you will want to make sure that you have all of the build tools
 
 This part is super simple.  However, there is some configuration that we need to do to ensure things are configured correctly.
 
-### Configuring VS Code
-
-First, we need to set up IntelliSense. This isn't strictly required, but it will make your life a LOT easier. To do this, we need to create the `.vscode/c_cpp_properties.json` file in the QMK Firmware folder, You can do this all manually, but I've done most of the work already. 
-
-Grab [this file](https://gist.github.com/drashna/48e2c49ce877be592a1650f91f8473e8) and save it.  You may need to edit this file, if you didn't install MSYS2 to the default location, or are using WSL/LxSS.  
-
-Once you have saved this file, you will need to reload VS Code, if it was already running. 
-
-?> You should see an `extensions.json` and `settings.json` file in the `.vscode` folder, as well.
-
+#### MSYS2 Setup
 
 Now, we will set up the MSYS2 window to show up in VSCode as the integrated terminal.  This has a number of advantages. Mostly, you can control+click on errors and jump to those files.  This makes debugging much easier.  It's also nice, in that you don't have to jump to another window. 
 
@@ -110,8 +101,50 @@ This installs a bunch of Git related tools that may make using Git with QMK Firm
 Restart once you've installed any extensions
 
 # Configure VS Code for QMK
+
 1. Click <kbd><kbd>File</kbd> > <kbd>Open Folder</kbd></kbd>
 2. Open the QMK Firmware folder that you cloned from GitHub. 
 3. Click <kbd><kbd>File</kbd> > <kbd>Save Workspace As...</kbd></kbd>
 
+## Configuring VS Code
+
+Using the [standard `compile_commands.json` database](https://clang.llvm.org/docs/JSONCompilationDatabase.html), we can get VS code C/C++ extension to use the exact same includes and defines used for your keyboard and keymap. 
+
+1. Run `qmk generate-compilation-database -kb <keyboard> -km <keymap>` to generate the `compile_commands.json`.
+1. Create `.vscode/c_cpp_properties.json` with the following content:
+```
+{
+    "configurations": [
+        {
+            "name": "qmk",
+            "compilerArgs": ["-mmcu=atmega32u4"],
+            "compilerPath": "/usr/bin/avr-gcc",
+            "cStandard": "gnu11",
+            "cppStandard": "gnu++14",
+            "compileCommands": "${workspaceFolder}/compile_commands.json",
+            "intelliSenseMode": "linux-gcc-arm",
+            "browse": {
+                "path": [
+                    "${workspaceFolder}"
+                ],
+                "limitSymbolsToIncludedHeaders": true,
+                "databaseFilename": ""
+            }
+        }
+    ],
+    "version": 4
+}
+```
+
+Change values in `.vscode/c_cpp_properties.json` for your environment:
+
+1. Copy the `-mmcu` argument from `compile_commands.json` into your `compilerArgs`. This is to work around a [bug in vscode c/c++ extension](https://github.com/microsoft/vscode-cpptools/issues/6478).
+1. Use the `compilerPath` from `compile_commands.json`.
+1. Modify `cStandard`, `cppStandard` and `intelliSenseMode` values to the correct values for your platform. See [this section](https://code.visualstudio.com/docs/cpp/c-cpp-properties-schema-reference#_configuration-properties) for reference. For WSL, it should still be gcc-x64.
+
 And now you're ready to code QMK Firmware in VS Code
+
+
+## Troubleshooting VSCode C/C++ extension
+
+If the defines are not matching what you expect, open the source code and run action `C/C++: Log Diagnostics`. This will list the exact list of defines and include paths defined in `compile_commands.json`, and if it's not part of your compilation database, it will tell you so.

docs/pr_checklist.md

@@ -53,6 +53,7 @@ https://github.com/qmk/qmk_firmware/pulls?q=is%3Apr+is%3Aclosed+label%3Akeyboard
 
 - keyboard moves within the repository *must* go through the `develop` branch instead of `master`, so as to ensure compatibility for users
     - `data/mappings/keyboard_aliases.hjson` must be updated to reflect the move, so users with pre-created configurator keymap.json files continue to detect the correct keyboard
+- keyboard updates and refactors (eg. to data driven) *must* go through `develop` to reduce `master` -> `develop` merge conflicts
 - PR submissions from a `kbfirmware` export (or equivalent) will not be accepted unless converted to new QMK standards -- try `qmk import-kbfirmware` first
 - `info.json`
     - With the move to [data driven](https://docs.qmk.fm/#/data_driven_config) keyboard configuration, we encourage contributors to utilise as many features as possible of the info.json [schema](https://github.com/qmk/qmk_firmware/blob/master/data/schemas/keyboard.jsonschema).