Merge branch 'qmk:master' into master

.github/workflows/ci_builds.yml

@@ -0,0 +1,40 @@
+name: CI Builds
+
+permissions:
+  contents: read
+
+on:
+  push:
+    branches:
+    - master
+    - develop
+
+jobs:
+  ci_builds:
+    name: "CI Build"
+    runs-on: self-hosted
+    timeout-minutes: 1380
+
+    if: github.repository == 'qmk/qmk_firmware'
+
+    strategy:
+      matrix:
+        keymap:
+        - default
+        - via
+
+    container: qmkfm/qmk_cli
+
+    steps:
+    - name: Disable safe.directory check
+      run : git config --global --add safe.directory '*'
+
+    - uses: actions/checkout@v3
+      with:
+        submodules: recursive
+
+    - 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 }}

docs/feature_combo.md

@@ -20,32 +20,38 @@ combo_t key_combos[COMBO_COUNT] = {
 
 This will send "Escape" if you hit the A and B keys, and Ctrl+Z when you hit the C and D keys.
 
-As of [PR#8591](https://github.com/qmk/qmk_firmware/pull/8591/), it is possible to fire combos from ModTap keys and LayerTap keys. So in the above example you could have keys `LSFT_T(KC_A)` and `LT(_LAYER, KC_B)` and it would work. So Home Row Mods and Home Row Combos at same time is now a thing!
+## Mod-Tap Support
+[Mod-Tap](mod_tap.md) feature is also supported together with combos. You will need to use the full Mod-Tap keycode in the combo definition, e.g.:
 
-It is also now possible to overlap combos. Before, with the example below both combos would activate when all three keys were pressed. Now only the three key combo will activate.
+```c
+const uint16_t PROGMEM test_combo1[] = {LSFT_T(KC_A), LT(1, KC_B), COMBO_END};
+```
+
+## Overlapping Combos
+It is possible to overlap combos. Before, with the example below both combos would activate when all three keys were pressed. Now only the three key combo will activate.
 
 ```c
-const uint16_t PROGMEM test_combo1[] = {LSFT_T(KC_A), LT(_LAYER, KC_B), COMBO_END};
-const uint16_t PROGMEM test_combo2[] = {LSFT_T(KC_A), LT(_LAYER, KC_B), KC_C, COMBO_END};
+const uint16_t PROGMEM test_combo1[] = {LSFT_T(KC_A), LT(1, KC_B), COMBO_END};
+const uint16_t PROGMEM test_combo2[] = {LSFT_T(KC_A), LT(1, KC_B), KC_C, COMBO_END};
 combo_t key_combos[COMBO_COUNT] = {
     COMBO(test_combo1, KC_ESC)
     COMBO(test_combo2, KC_TAB)
 };
 ```
 
-Executing more complex keycodes like ModTaps and LayerTaps is now also possible.
-
 ## Examples
 
-If you want to add a list, then you'd use something like this:
+A long list of combos can be defined in an `enum` list that ends with `COMBO_LENGTH` and you can leave `COMBO_COUNT` undefined:
 
 ```c
 enum combos {
   AB_ESC,
   JK_TAB,
   QW_SFT,
   SD_LAYER,
+  COMBO_LENGTH
 };
+uint16_t COMBO_LEN = COMBO_LENGTH; // remove the COMBO_COUNT define and use this instead!
 
 const uint16_t PROGMEM ab_combo[] = {KC_A, KC_B, COMBO_END};
 const uint16_t PROGMEM jk_combo[] = {KC_J, KC_K, COMBO_END};
@@ -61,7 +67,6 @@ combo_t key_combos[COMBO_COUNT] = {
 ```
 
 For a more complicated implementation, you can use the `process_combo_event` function to add custom handling.
-Additionally, this example shows how you can leave `COMBO_COUNT` undefined.
 
 ```c
 enum combo_events {
@@ -111,13 +116,13 @@ You can enable, disable and toggle the Combo feature on the fly. This is useful
 |`QK_COMBO_OFF`   |`CM_OFF` |Turns off Combo feature         |
 |`QK_COMBO_TOGGLE`|`CM_TOGG`|Toggles Combo feature on and off|
 
-# Advanced Configuration
+## Advanced Configuration
 These configuration settings can be set in your `config.h` file.
 
-## Combo Term
+### Combo Term
 By default, the timeout for the Combos to be recognized is set to 50ms. This can be changed if accidental combo misfires are happening or if you're having difficulties pressing keys at the same time. For instance, `#define COMBO_TERM 40` would set the timeout period for combos to 40ms.
 
-## Buffer and state sizes
+### Buffer and state sizes
 If you're using long combos, or you have a lot of overlapping combos, you may run into issues with this, as the buffers may not be large enough to accommodate what you're doing. In this case, you can configure the sizes of the buffers used. Be aware, larger combo sizes and larger buffers will increase memory usage!
 
 To configure the amount of keys a combo can be composed of, change the following:
@@ -138,13 +143,13 @@ Processing combos has two buffers, one for the key presses, another for the comb
 | `#define COMBO_KEY_BUFFER_LENGTH 8` | 8 (the key amount `(EXTRA_)EXTRA_LONG_COMBOS` gives) |
 | `#define COMBO_BUFFER_LENGTH 4`     | 4                                                    |
 
-## Modifier Combos
+### Modifier Combos
 If a combo resolves to a Modifier, the window for processing the combo can be extended independently from normal combos. By default, this is disabled but can be enabled with `#define COMBO_MUST_HOLD_MODS`, and the time window can be configured with `#define COMBO_HOLD_TERM 150` (default: `TAPPING_TERM`). With `COMBO_MUST_HOLD_MODS`, you cannot tap the combo any more which makes the combo less prone to misfires.
 
-## Strict key press order
+### Strict key press order
 By defining `COMBO_MUST_PRESS_IN_ORDER` combos only activate when the keys are pressed in the same order as they are defined in the key array.
 
-## Per Combo Timing, Holding, Tapping and Key Press Order
+### Per Combo Timing, Holding, Tapping and Key Press Order
 For each combo, it is possible to configure the time window it has to pressed in, if it needs to be held down, if it needs to be tapped, or if its keys need to be pressed in order.
 
 For example, tap-only combos are useful if any (or all) of the underlying keys are mod-tap or layer-tap keys. When you tap the combo, you get the combo result. When you press the combo and hold it down, the combo doesn't activate. Instead the keys are processed separately as if the combo wasn't even there.
@@ -234,7 +239,7 @@ bool get_combo_must_press_in_order(uint16_t combo_index, combo_t *combo) {
 }
 ```
 
-## Generic hook to (dis)allow a combo activation
+### Generic hook to (dis)allow a combo activation
 
 By defining `COMBO_SHOULD_TRIGGER` and its companying function `bool combo_should_trigger(uint16_t combo_index, combo_t *combo, uint16_t keycode, keyrecord_t *record)` you can block or allow combos to activate on the conditions of your choice.
 For example, you could disallow some combos on the base layer and allow them on another. Or disable combos on the home row when a timer is running.
@@ -254,7 +259,7 @@ bool combo_should_trigger(uint16_t combo_index, combo_t *combo, uint16_t keycode
 }
 ```
 
-## Variable Length Combos
+### Variable Length Combos
 If you leave `COMBO_COUNT` undefined in `config.h`, it allows you to programmatically declare the size of the Combo data structure and avoid updating `COMBO_COUNT`. Instead a variable called `COMBO_LEN` has to be set. It can be set with something similar to the following in `keymap.c`: `uint16_t COMBO_LEN = ARRAY_SIZE(key_combos);` or by adding `COMBO_LENGTH` as the *last* entry in the combo enum and then `uint16_t COMBO_LEN = COMBO_LENGTH;` as such:
 ```c
 enum myCombos {
@@ -266,26 +271,26 @@ uint16_t COMBO_LEN = COMBO_LENGTH;
 Regardless of the method used to declare `COMBO_LEN`, this also requires to convert the `combo_t key_combos[COMBO_COUNT] = {...};` line to `combo_t key_combos[] = {...};`.
 
 
-## Combo timer
+### Combo timer
 
 Normally, the timer is started on the first key press and then reset on every subsequent key press within the `COMBO_TERM`.
 Inputting combos is relaxed like this, but also slightly more prone to accidental misfires.
 
 The next two options alter the behaviour of the timer.
 
-### `#define COMBO_STRICT_TIMER`
+#### `#define COMBO_STRICT_TIMER`
 
 With `COMBO_STRICT_TIMER`, the timer is started only on the first key press.
 Inputting combos is now less relaxed; you need to make sure the full chord is pressed within the `COMBO_TERM`.
 Misfires are less common but if you type multiple combos fast, there is a
 chance that the latter ones might not activate properly.
 
-### `#define COMBO_NO_TIMER`
+#### `#define COMBO_NO_TIMER`
 
 By defining `COMBO_NO_TIMER`, the timer is disabled completely and combos are activated on the first key release.
 This also disables the "must hold" functionalities as they just wouldn't work at all.
 
-## Customizable key releases
+### Customizable key releases
 
 By defining `COMBO_PROCESS_KEY_RELEASE` and implementing the function `bool process_combo_key_release(uint16_t combo_index, combo_t *combo, uint8_t key_index, uint16_t keycode)`, you can run your custom code on each key release after a combo was activated. For example you could change the RGB colors, activate haptics, or alter the modifiers.
 
@@ -322,13 +327,13 @@ bool process_combo_key_release(uint16_t combo_index, combo_t *combo, uint8_t key
     return false;
 }
 ```
-## Layer independent combos
+### Layer independent combos
 
 If you, for example, use multiple base layers for different key layouts, one for QWERTY, and another one for Colemak, you might want your combos to work from the same key positions on all layers. Defining the same combos again for another layout is redundant and takes more memory. The solution is to just check the keycodes from one layer.
 
 With `#define COMBO_ONLY_FROM_LAYER 0` in config.h, the combos' keys are always checked from layer `0`, even if other layers are active.
 
-### Combo reference layers by layer.
+#### Combo reference layers by layer.
 
 If not using `COMBO_ONLY_FROM_LAYER` it is possible to specify a
 combo reference layer for any layer using the `combo_ref_from_layer` hook. 
@@ -385,7 +390,7 @@ In addition to the keycodes, there are a few functions that you can use to set t
 | `is_combo_enabled()` | Returns the status of the combo feature state (true or false) |
 
 
-# Dictionary Management
+## Dictionary Management
 
 Having 3 places to update when adding new combos or altering old ones does become cumbersome when you have a lot of combos. We can alleviate this with some magic! ... If you consider C macros magic.
 First, you need to add `VPATH += keyboards/gboards` to your `rules.mk`. Next, include the file `g/keymap_combo.h` in your `keymap.c`.

docs/feature_split_keyboard.md

@@ -79,6 +79,16 @@ If you're using a custom transport (communication method), then you will also ne
 SPLIT_TRANSPORT = custom
 ```
 
+### Layout Macro
+
+Configuring your layout in a split keyboard works slightly differently to a non-split keyboard. Take for example the following layout. The top left numbers refer to the matrix row and column, and the bottom right are the order of the keys in the layout:
+
+![Physical layout](https://i.imgur.com/QeY6kMQ.png)
+
+Since the matrix scanning procedure operates on entire rows, it first populates the left half's rows, then the right half's. Thus, the matrix as QMK views it has double the rows instead of double the columns:
+
+![Matrix](https://i.imgur.com/4wjJzBU.png)
+
 ### Setting Handedness
 
 By default, the firmware does not know which side is which; it needs some help to determine that. There are several ways to do this, listed in order of precedence.

docs/newbs_building_firmware_workflow.md

@@ -106,6 +106,9 @@ jobs:
 
     steps:
 
+    - name: Disable git safe directory checks
+      run : git config --global --add safe.directory '*'
+
     - name: Checkout QMK
       uses: actions/checkout@v3
       with:

docs/porting_your_keyboard_to_qmk.md

@@ -150,6 +150,8 @@ In the above example,
   * It must conform to the [layout guidelines](hardware_keyboard_guidelines.md#ltkeyboard_namehgt)
 * `"matrix": [0, 0]` defines the electrical position
 
+?> See also: [Split Keyboard Layout Macro](https://docs.qmk.fm/#/feature_split_keyboard?id=layout-macro) and [Matrix to Physical Layout](https://docs.qmk.fm/#/understanding_qmk?id=matrix-to-physical-layout-map).
+
 ## Additional Configuration
 
 There are a lot of features that can be turned on or off, configured or tuned. Some of these have yet to be migrated over to [Data Driven Configuration](data_driven_config.md). The following sections cover the process for when an `info.json` option is unavailable.

docs/pr_checklist.md

@@ -69,15 +69,25 @@ https://github.com/qmk/qmk_firmware/pulls?q=is%3Apr+is%3Aclosed+label%3Akeyboard
             - If the keyboard has multiple electrical/switch layouts:
                 - include a `LAYOUT_all` which specifies all possible layout positions in the electrical matrix
                 - use alternate layout names for all other possible layouts, preferring community layout names if an equivalent is available (e.g. `LAYOUT_tkl_ansi`, `LAYOUT_ortho_4x4` etc.)
+        - Microcontroller and bootloader
+        - Diode Direction (if not using direct pins)
+    - the following are required to be configured in `info.json` if necessary
+      - Direct pin configuration
+      - Backlight Configuration (where applicable)
+      - Split keyboard configuration (where applicable)
+      - Encoder Configuration
+      - Bootmagic Configuration
+      - LED Indicator Configuration
 - `readme.md`
-    - standard template should be present -- [link to template](https://github.com/qmk/qmk_firmware/blob/master/data/templates/keyboard/readme.md)
+    - must follow the [template](https://github.com/qmk/qmk_firmware/blob/master/data/templates/keyboard/readme.md)
     - flash command is present, and has `:flash` at end
     - valid hardware availability link (unless handwired) -- private groupbuys are okay, but one-off prototypes will be questioned. If open-source, a link to files should be provided.
     - clear instructions on how to reset the board into bootloader mode
     - a picture about the keyboard and preferably about the PCB, too
         - images are not to be placed in the `qmk_firmware` repository
         - images should be uploaded to an external image hosting service, such as [imgur](https://imgur.com/).
-        - if imgur is used, images should be resized appropriately: append "h" to the image url i.e. `https://i.imgur.com/vqgE7Ok.jpg` becomes `https://i.imgur.com/vqgE7Okh.jpg`
+        - if imgur is used, images should be resized appropriately: append "h" to the image url i.e. [https://i.imgur.com/vqgE7Ok.jpg](https://i.imgur.com/vqgE7Ok.jpg) becomes [https://i.imgur.com/vqgE7Ok**h**.jpg](https://i.imgur.com/vqgE7Okh.jpg)
+        - image links should link directly to the image, not a "preview" -- i.e. [https://imgur.com/vqgE7Ok](https://imgur.com/vqgE7Ok) should be [https://i.imgur.com/vqgE7Okh.jpg](https://i.imgur.com/vqgE7Okh.jpg) when using imgur
 - `rules.mk`
     - removed `MIDI_ENABLE`, `FAUXCLICKY_ENABLE` and `HD44780_ENABLE`
     - modified `# Enable Bluetooth with the Adafruit EZ-Key HID` -> `# Enable Bluetooth`
@@ -88,11 +98,17 @@ https://github.com/qmk/qmk_firmware/pulls?q=is%3Apr+is%3Aclosed+label%3Akeyboard
       - `COMBO_ENABLE`
       - `ENCODER_MAP_ENABLE`
 - keyboard `config.h`
-    - don't repeat `MANUFACTURER` in the `PRODUCT` value
     - no `#define DESCRIPTION`
     - no Magic Key Options, MIDI Options or HD44780 configuration
     - user preference configurable `#define`s need to be moved to keymap `config.h`
-    - "`DEBOUNCE`" instead of "`DEBOUNCING_DELAY`"
+    - default values should not be redefined, such as `DEBOUNCE`, RGB related settings, etc.
+      - feature specific documentation contains most default values
+      - `grep` or alternative tool can be used to search for default values in core directories (e.g. `grep -r "define DEBOUNCE" quantum`)
+    - no copy/pasted comment blocks explaining a feature and/or its caveats -- this is what the docs are for
+      - `Force NKRO to be enabled ... toggled again during a power-up`
+      - commented-out unused defines, such as RGB effects
+    - no `#include "config_common.h`
+    - no `#define MATRIX_ROWS/COLS`, unless necessary (e.g. a keyboard with a custom matrix)
     - bare minimum required code for a board to boot into QMK should be present
         - initialisation code for the matrix and critical devices
         - mirroring existing functionality of a commercial board (like custom keycodes and special animations etc.) should be handled through non-`default` keymaps
@@ -104,31 +120,26 @@ https://github.com/qmk/qmk_firmware/pulls?q=is%3Apr+is%3Aclosed+label%3Akeyboard
     - `matrix_init_board()` etc. migrated to `keyboard_pre_init_kb()`, see: [keyboard_pre_init*](custom_quantum_functions.md?id=keyboard_pre_init_-function-documentation)
     - prefer `CUSTOM_MATRIX = lite` if custom matrix used, allows for standard debounce, see [custom matrix 'lite'](custom_matrix.md?id=lite)
     - prefer LED indicator [Configuration Options](feature_led_indicators.md?id=configuration-options) to custom `led_update_*()` implementations where possible
-    - Encoder support should not require any keyboard-level code, and associated keymaps should now leverage the [Encoder Map](feature_encoders.md?id=encoder-map) feature instead.
+    - hardware that's enabled at the keyboard level and requires configuration such as OLED displays or encoders should have basic functionality implemented here
 - `<keyboard>.h`
     - `#include "quantum.h"` appears at the top
     - `LAYOUT` macros should be moved to `info.json`
 - keymap `config.h`
     - no duplication of `rules.mk` or `config.h` from keyboard
 - `keymaps/default/keymap.c`
-    - `QMKBEST`/`QMKURL` removed
-    - if using `MO(_LOWER)` and `MO(_RAISE)` keycodes or equivalent, and the keymap has an adjust layer when holding both keys -- if the keymap has no "direct-to-adjust" keycode (such as `MO(_ADJUST)`) then you should prefer to write...
-        ```
-        layer_state_t layer_state_set_user(layer_state_t state) {
-          return update_tri_layer_state(state, _LOWER, _RAISE, _ADJUST);
-        }
-        ```
-        ...instead of manually handling `layer_on()`, `update_tri_layer()` inside the keymap's `process_record_user()`.
+    - `QMKBEST`/`QMKURL` example macros removed
+    - if using `MO(1)` and `MO(2)` keycodes together to access a third layer, the [Tri Layer](https://docs.qmk.fm/#/feature_tri_layer) feature should be used, rather than manually implementing this using `layer_on/off()` and `update_tri_layer()` functions in the keymap's `process_record_user()`.
 - default (and via) keymaps should be "pristine"
     - bare minimum to be used as a "clean slate" for another user to develop their own user-specific keymap
     - standard layouts preferred in these keymaps, if possible
+    - should use [encoder map feature](https://docs.qmk.fm/#/feature_encoders?id=encoder-map), rather than `encoder_update_user()`
     - default keymap should not enable VIA -- the VIA integration documentation requires a keymap called `via`
 - submitters can have a personal (or bells-and-whistles) keymap showcasing capabilities in the same PR but it shouldn't be embedded in the 'default' keymap
 - submitters can also have a "manufacturer-matching" keymap that mirrors existing functionality of the commercial product, if porting an existing board
 - Do not include VIA json files in the PR. These do not belong in the QMK repository as they are not used by QMK firmware -- they belong in the [VIA Keyboard Repo](https://github.com/the-via/keyboards)
 - Do not include KLE json files in the PR. These have no use within QMK.
 - Do not include source files from another keyboard or vendors keyboard folder. Including core files is fine.
-  - For instance, only `wilba_tech` boards shall include `keyboards/wilba_tech/wt_main.c` and  `keyboards/wilba_tech/wt_rgb_backlight.c`. But including `drivers/sensors/pmw3360.c` is absolutely fine for any and all boards.
+  - For instance, only `wilba_tech` boards shall include `keyboards/wilba_tech/wt_main.c` and  `keyboards/wilba_tech/wt_rgb_backlight.c`. But including `drivers/sensors/pmw3360.c` is absolutely fine for any and all boards that require it.
   - Code that needs to be used by multiple boards is a candidate for core code changes, and should be separated out.
 
 Also, specific to ChibiOS:

keyboards/binepad/bn009/config.h

@@ -16,7 +16,6 @@
 
 #pragma once
 
-
 #define MATRIX_ROW_PINS { D2, D1, D0 }
 #define MATRIX_COL_PINS { B6, B5, B4 }