Remove IGNORE_MOD_TAP_INTERRUPT_PER_KEY in favour of HOLD_ON_OTHER_KEY_PRESS_PER_KEY (#15741)

1 files changed, 43 insertions, 0 deletions

diff --git a/docs/ChangeLog/20230226/PR15741.md b/docs/ChangeLog/20230226/PR15741.md
new file mode 100644
index 0000000000..385816d65b
--- /dev/null
+++ b/docs/ChangeLog/20230226/PR15741.md
@@ -0,0 +1,43 @@
+`IGNORE_MOD_TAP_INTERRUPT_PER_KEY` has been removed and `IGNORE_MOD_TAP_INTERRUPT` deprecated as a stepping stone towards making `IGNORE_MOD_TAP_INTERRUPT` the new default behavior for mod-taps in the future.
+
+In place of the now removed `IGNORE_MOD_TAP_INTERRUPT_PER_KEY`, one must use the pre-existing `HOLD_ON_OTHER_KEY_PRESS` option.
+
+In most cases, updating `get_ignore_mod_tap_interrupt` to `get_hold_on_other_key_press` is simply a matter of renaming the function and swapping every `true` by `false` and vice versa. The one subtlety you may need to look out for is that the `get_ignore_mod_tap_interrupt` was only ever called with mod-taps passed in as the `keycode` argument, while the `keycode` argument of `get_hold_on_other_key_press` can be any dual-role key. This includes not only mod-taps, but also layer-taps, one shot keys, `TT(layer)` and more. This has an impact on the effect of the `default` case in a typical per-key configuration making use of a `switch(keycode)` statement.
+
+To illustrate, let's take the example of a configuration where we'd want all mod-taps to activate the modifier if another key is pressed while held with the exception of `LCTL_T(KC_A)`, which should ignore keys pressed while it is held and activate the modifier only if it has been held for longer than the tapping term. In addition, we would like to keep the default "ignore-interrupt" behavior of layer taps.
+
+An old way to do this would be via the following code:
+
+```c
+bool get_ignore_mod_tap_interrupt(uint16_t keycode, keyrecord_t *record) {
+    switch(keycode) {
+        case LCTL_T(KC_A):
+            return true;
+        default:
+            return false;
+    }
+}
+```
+
+The correct way to update this code without accidentally changing how the layer-taps work would be the following:
+
+```c
+bool get_hold_on_other_key_press(uint16_t keycode, keyrecord_t *record) {
+    switch(keycode) {
+        // Capture all mod-tap keycodes.
+        case QK_MOD_TAP ... QK_MOD_TAP_MAX:
+            if (keycode == LCTL_T(KC_A)) {
+                // Disable HOLD_ON_OTHER_KEY_PRESS for LCTL_T(KC_A)
+                // aka enable IGNORE_MOD_TAP_INTERRUPT for LCTL_T(KC_A).
+                return false;
+            } else {
+                // Enable HOLD_ON_OTHER_KEY_PRESS for every other mod-tap keycode.
+                return true;
+            }
+        default:
+            return false;
+    }
+}
+```
+
+For more information, you are invited to read the sections on [IGNORE_MOD_TAP_INTERRUPT](tap_hold.md#ignore-mod-tap-interrupt) and [HOLD_ON_OTHER_KEY_PRESS](tap_hold.md#hold-on-other-key-press) in the page on [Tap-Hold configuration options](tap_hold.md).