diff options
Diffstat (limited to 'docs')
88 files changed, 3207 insertions, 1501 deletions
diff --git a/docs/ChangeLog/20211127.md b/docs/ChangeLog/20211127.md index d954bb9f61..0780ab6a44 100644 --- a/docs/ChangeLog/20211127.md +++ b/docs/ChangeLog/20211127.md @@ -56,19 +56,19 @@ You can now define up to 32 macros in your `keymap.json` file, as used by [QMK C "keyboard": "handwired/my_macropad", "keymap": "my_keymap", "macros": [ - [ // first listed is MACRO_0... + [ // first listed is QK_MACRO_0... {"action":"down", "keycodes": ["LSFT"]}, "hello world1", {"action": "up","keycodes": ["LSFT"]} ], - [ // ...then MACRO_1... + [ // ...then QK_MACRO_1... {"action":"tap", "keycodes": ["LCTL", "LALT", "DEL"]} ], - [ // ...then MACRO_2... + [ // ...then QK_MACRO_2... "ding!", {"action":"beep"} ], - [ // ...and MACRO_3. + [ // ...and QK_MACRO_3. {"action":"tap", "keycodes": ["F1"]}, {"action":"delay", "duration": "1000"}, {"action":"tap", "keycodes": ["PGDN"]} @@ -76,7 +76,7 @@ You can now define up to 32 macros in your `keymap.json` file, as used by [QMK C ], "layout": "LAYOUT_all", "layers": [ - ["MACRO_0", "MACRO_1", "MACRO_2", "MACRO_3"] + ["QK_MACRO_0", "QK_MACRO_1", "QK_MACRO_2", "QK_MACRO_3"] ] } ``` diff --git a/docs/ChangeLog/20221126.md b/docs/ChangeLog/20221126.md new file mode 100644 index 0000000000..82aa4a499e --- /dev/null +++ b/docs/ChangeLog/20221126.md @@ -0,0 +1,510 @@ +# QMK Breaking Changes - 2022 November 26 Changelog + +## Notable Features :id=notable-features + +### Autocorrect ([#15699](https://github.com/qmk/qmk_firmware/pull/15699)) :id=autocorrect + +_@getreuer_ in their infinite wisdom decided that autocorrect was a feature needed by QMK. As is customary, _@drashna_ adapted it to core and got it into a state that everyone else can use it. See [Feature: Autocorrect](feature_autocorrect.md) for more ifnormation (grin). + +## Changes Requiring User Action :id=changes-requiring-user-action + +### Updated Keyboard Codebases :id=updated-keyboard-codebases + +The following keyboards have had their source moved within QMK: + +| Old Keyboard Name | New Keyboard Name | +|--------------------------------------|--------------------------------------| +| converter/numeric_keypad_IIe | converter/numeric_keypad_iie | +| durgod/k3x0/k310 | durgod/k310 | +| durgod/k3x0/k320 | durgod/k320 | +| emptystring/NQG | emptystring/nqg | +| handwired/hillside/46 | hillside/46 | +| handwired/hillside/48 | hillside/48 | +| handwired/hillside/52 | hillside/52 | +| maple_computing/christmas_tree/V2017 | maple_computing/christmas_tree/v2017 | + +### Keycodes refactoring :id=keycodes-overhaul-user-action + +QMK's keycodes got a very significant overhaul this breaking changes cycle, with the bulk of the work done by _@zvecr_ and _@fauxpark_ -- renaming, reordering, removing has been their focus in this area. In an attempt to standardise interoperation with host applications, keycode values now have strong versioning so that any connected application has confidence that the keys it thinks exist on the board actually match up with what's compiled in. These strongly-versioned keycode definitions are now published online and will not change, so tools that remap keycodes have a reference to work with. In future versions of QMK, any new or changed keycodes will result in a new version specification. See [API docs](api_docs.md#qmk-constants) for more information on the published versions if you're writing a tool to manage keycodes. + +In most cases user keymaps in the repository have already been updated to reflect the new naming scheme. In some cases user keymaps outside the repository may strike a missing keycode with the old name -- it's highly likely that the name had already been deprecated for some time, and should have been updated previously. + +See below for the full list of changesets. + +!> Keycode aliases have been put in place in most cases to cater for "old names" being mapped to "new names" -- the documentation already reflects all the new naming of keys. + +### Configuration Item Refactoring :id=config-refactoring + +A number of configuration items have been renamed for consistency. + +RGB Matrix configuration: + +| Old Config | New Config | +|-------------------------|-------------------------| +| DRIVER_LED_COUNT | RGB_MATRIX_LED_COUNT | +| RGB_DISABLE_TIMEOUT | RGB_MATRIX_TIMEOUT | +| RGB_MATRIX_STARTUP_HUE | RGB_MATRIX_DEFAULT_HUE | +| RGB_MATRIX_STARTUP_MODE | RGB_MATRIX_DEFAULT_MODE | +| RGB_MATRIX_STARTUP_SAT | RGB_MATRIX_DEFAULT_SAT | +| RGB_MATRIX_STARTUP_SPD | RGB_MATRIX_DEFAULT_SPD | +| RGB_MATRIX_STARTUP_VAL | RGB_MATRIX_DEFAULT_VAL | + +LED Matrix configuration: + +| Old Config | New Config | +|-------------------------|-------------------------| +| DRIVER_LED_COUNT | LED_MATRIX_LED_COUNT | +| LED_DISABLE_TIMEOUT | LED_MATRIX_TIMEOUT | +| LED_MATRIX_STARTUP_MODE | LED_MATRIX_DEFAULT_MODE | +| LED_MATRIX_STARTUP_SPD | LED_MATRIX_DEFAULT_SPD | +| LED_MATRIX_STARTUP_VAL | LED_MATRIX_DEFAULT_VAL | + +Joystick configuration: + +| Old Config | New Config | +|--------------------------|--------------------------| +| JOYSTICK_AXES_COUNT | JOYSTICK_AXIS_COUNT | +| JOYSTICK_AXES_RESOLUTION | JOYSTICK_AXIS_RESOLUTION | + +### Data-driven USB IDs Refactoring ([#18152](https://github.com/qmk/qmk_firmware/pull/18152)) :id=usb-ids-Refactoring + +QMK has decided to deprecate the specification of USB IDs inside `config.h` in favour of `info.json`, leaving data-driven as the only method to specify USB information. As per the deprecation schedule put forward last breaking changes cycle, USB information must be specified in `info.json` instead. + +Previously in `config.h`: +```c +#define VENDOR_ID 0x1234 +#define PRODUCT_ID 0x5678 +#define DEVICE_VER 0x0001 +#define MANUFACTURER Me +#define PRODUCT MyKeyboard +``` + +Replaced by `info.json`: +```json +{ + "keyboard_name": "MyKeyboard", + "manufacturer": "Me", + "usb": { + "vid": "0x1234", + "pid": "0x5678", + "device_version": "0.0.1" + } +} +``` + +### LED Indicator callback refactoring ([#14864](https://github.com/qmk/qmk_firmware/pull/18450)) :id=led-callback-refactor + +_RGB Matrix_ and _LED Matrix_ Indicator display code was traditionally difficult to override in keymaps as they did not follow the standard pattern of `bool *_kb()` deferring to `bool *_user()` functions, allowing signalling to the higher level that processing had already been done. + +This changes the standard callback model to allow for a base implementation to be provided by a keyboard, but also still allow for keymap-level overrides without needing to modify the keyboard's code. + +The old RGB Matrix keymap code went something like this: + +```c +void rgb_matrix_indicators_user(void) { + // keymap LED code +} +``` + +...but the new RGB Matrix keymap code looks like this: +```c +bool rgb_matrix_indicators_user(void) { + // keymap LED code + return false; +} +``` + +Keyboard designers should now structure their keyboard-level routines like the following, in order to allow for keymap overrides: + +```c +bool rgb_matrix_indicators_kb(void) { + // Defer to the keymap if they want to override + if (!rgb_matrix_indicators_user()) { return false; } + + // keyboard LED code + return true; +} +``` + +The equivalent transformations should be done for LED Matrix boards. + +### Unicode mode refactoring :id=unicode-mode-renaming + +Unicode modes were renamed in order to prevent collision with equivalent keycodes. The available values for `UNICODE_SELECTED_MODES` changed -- see [Feature: Unicode](feature_unicode.md#setting-the-input-mode) for the new list of values and how to configure them. + +## Notable core changes :id=notable-core + +This breaking changes cycle, a lot of the core changes are related to cleanup and refactoring -- commonly called "tech debt". + +### Keycodes refactoring :id=keycodes-overhaul-core-changes + +We aren't going to list each and every change -- they're far too numerous -- instead, we'll just list the related PRs in order to convey just how wide-reaching these changes were: + +* Align audio keycode names ([#18962](https://github.com/qmk/qmk_firmware/pull/18962)) +* Align dynamic tapping term keycode names ([#18963](https://github.com/qmk/qmk_firmware/pull/18963)) +* Align haptic feedback keycode names ([#18964](https://github.com/qmk/qmk_firmware/pull/18964)) +* Deprecate `CAPS_WORD`/`CAPSWRD` for `CW_TOGG` ([#18834](https://github.com/qmk/qmk_firmware/pull/18834)) +* Deprecate `KC_LEAD` for `QK_LEAD` ([#18792](https://github.com/qmk/qmk_firmware/pull/18792)) +* Deprecate `KC_LOCK` for `QK_LOCK` ([#18796](https://github.com/qmk/qmk_firmware/pull/18796)) +* Deprecate `KEY_OVERRIDE_*` keycodes for `KO_*` ([#18843](https://github.com/qmk/qmk_firmware/pull/18843)) +* Deprecate `ONESHOT_*` keycodes for `QK_ONE_SHOT_*` ([#18844](https://github.com/qmk/qmk_firmware/pull/18844)) +* Deprecate `SECURE_*` keycodes for `QK_SECURE_*` ([#18847](https://github.com/qmk/qmk_firmware/pull/18847)) +* Deprecate `VLK_TOG` for `VK_TOGG` ([#18807](https://github.com/qmk/qmk_firmware/pull/18807)) +* Initial DD keycode migration ([#18643](https://github.com/qmk/qmk_firmware/pull/18643)) +* Macro keycode name refactoring ([#18958](https://github.com/qmk/qmk_firmware/pull/18958)) +* Move mousekey keycodes into newly freed up keycode block ([#16076](https://github.com/qmk/qmk_firmware/pull/16076)) +* Normalise Auto Shift keycodes ([#18892](https://github.com/qmk/qmk_firmware/pull/18892)) +* Normalise Autocorrect keycodes ([#18893](https://github.com/qmk/qmk_firmware/pull/18893)) +* Normalise Combo keycodes ([#18877](https://github.com/qmk/qmk_firmware/pull/18877)) +* Normalise Dynamic Macro keycodes ([#18939](https://github.com/qmk/qmk_firmware/pull/18939)) +* Normalise Joystick and Programmable Button keycodes ([#18832](https://github.com/qmk/qmk_firmware/pull/18832)) +* Normalise MIDI keycodes ([#18972](https://github.com/qmk/qmk_firmware/pull/18972)) +* Normalise output selection (Bluetooth) keycodes ([#19004](https://github.com/qmk/qmk_firmware/pull/19004)) +* Normalise Space Cadet keycodes ([#18864](https://github.com/qmk/qmk_firmware/pull/18864)) +* Normalise Unicode keycodes ([#18898](https://github.com/qmk/qmk_firmware/pull/18898)) +* Publish constants metadata to API ([#19143](https://github.com/qmk/qmk_firmware/pull/19143)) +* Relocate US ANSI shifted keycode aliases ([#18634](https://github.com/qmk/qmk_firmware/pull/18634)) +* Remove `KC_DELT` ([#18882](https://github.com/qmk/qmk_firmware/pull/18882)) +* Remove `UNICODE_KEY_OSX` and `UC_OSX` ([#18290](https://github.com/qmk/qmk_firmware/pull/18290)) +* Remove deprecated RESET keycode alias ([#18271](https://github.com/qmk/qmk_firmware/pull/18271)) +* Remove legacy Debug keycode ([#18769](https://github.com/qmk/qmk_firmware/pull/18769)) +* Remove legacy EEPROM clear keycodes ([#18782](https://github.com/qmk/qmk_firmware/pull/18782)) +* Remove legacy fauxclicky and unicode keycodes ([#18800](https://github.com/qmk/qmk_firmware/pull/18800)) +* Remove legacy Grave Escape keycodes ([#18787](https://github.com/qmk/qmk_firmware/pull/18787)) +* Remove legacy international keycodes ([#18588](https://github.com/qmk/qmk_firmware/pull/18588)) +* Remove legacy keycodes, part 2 ([#18660](https://github.com/qmk/qmk_firmware/pull/18660)) +* Remove legacy keycodes, part 3 ([#18669](https://github.com/qmk/qmk_firmware/pull/18669)) +* Remove legacy keycodes, part 4 ([#18683](https://github.com/qmk/qmk_firmware/pull/18683)) +* Remove legacy keycodes, part 5 ([#18710](https://github.com/qmk/qmk_firmware/pull/18710)) +* Remove legacy keycodes, part 6 ([#18740](https://github.com/qmk/qmk_firmware/pull/18740)) +* Remove legacy locking caps/num/scroll keycodes ([#18601](https://github.com/qmk/qmk_firmware/pull/18601)) +* Remove legacy sendstring keycodes ([#18749](https://github.com/qmk/qmk_firmware/pull/18749)) +* Reworked backlight keycodes. ([#18961](https://github.com/qmk/qmk_firmware/pull/18961)) + +### Board Converters :id=board-converters + +There was additional work in the space of board converters -- historically QMK allowed for "converting" a Pro Micro build to a QMK Proton-C build. The last few versions of QMK have added support for replacement boards much like the Proton-C, and this quarter was no exception: + +* Add Bonsai C4 as a platform board file ([#18901](https://github.com/qmk/qmk_firmware/pull/18901)) +* Add converter support to keymap.json ([#18776](https://github.com/qmk/qmk_firmware/pull/18776)) +* Add Elite-C to converters ([#18309](https://github.com/qmk/qmk_firmware/pull/18309)) +* Add Elite-Pi converter ([#18236](https://github.com/qmk/qmk_firmware/pull/18236)) +* Allow QK_MAKE to work |