From d7541e1b7d799e16bf1ad116abcc84eced478f31 Mon Sep 17 00:00:00 2001
From: Jesse Vincent <jesse@keyboard.io>
Date: Sun, 7 Jun 2020 16:10:21 -0700
Subject: [PATCH 01/15] Add a test to the Makefile to complain if it can't find
 the Kaleidoscope bundle with a hint as to what the user might do to resolve
 things

Signed-off-by: Jesse Vincent <jesse@keyboard.io>
---
 examples/Devices/Keyboardio/Model01/Makefile | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/examples/Devices/Keyboardio/Model01/Makefile b/examples/Devices/Keyboardio/Model01/Makefile
index 996bde98..5b1d8127 100644
--- a/examples/Devices/Keyboardio/Model01/Makefile
+++ b/examples/Devices/Keyboardio/Model01/Makefile
@@ -48,8 +48,26 @@ KALEIDOSCOPE_BUILDER_DIR ?= $(ARDUINO_INSTALLED_ENV)/libraries/Kaleidoscope/bin/
 
 endif
 
+ifneq ("$(wildcard $(BOARD_HARDWARE_PATH)/$(KALEIDOSCOPE_PLUGIN_MAKEFILE_DIR)/rules.mk)","") 
 
 BOARD_HARDWARE_PATH ?= $(SKETCHBOOK_DIR)/hardware
 KALEIDOSCOPE_PLUGIN_MAKEFILE_DIR ?= keyboardio/avr/build-tools/makefiles/
 
 include $(BOARD_HARDWARE_PATH)/$(KALEIDOSCOPE_PLUGIN_MAKEFILE_DIR)/rules.mk
+
+else
+
+$(info ****************************************************************************)
+$(info I can't find an installed copy of Kaleidoscope's source code.)
+$(info )
+$(info This usually means you're attempting to build a device's firmware from a git)
+$(info checkout without having previously told Arduino where to find Kaleidoscope.)
+$(info )
+$(info It is probably the case that you want to move or symlink your git checkout )
+$(info of the Kaleidoscope bundle to the directory: ) 
+$(info )
+$(info   $(SKETCHBOOK_DIR)/hardware/keyboardio )
+$(info ****************************************************************************)
+
+
+endif

From 230d8e3c9b3ffd7cb43663eda3c3acdd73be133b Mon Sep 17 00:00:00 2001
From: Johannes Becker <alfalfasprossen@gmail.com>
Date: Mon, 8 Jun 2020 02:59:00 +0200
Subject: [PATCH 02/15] Use shift state to invert next/prev LED effect key
 direction

Handling of the respective keys is moved to `beforeReportingState`
as the state of shift is only then available. Usage together with
OneShot requires OneShot to be initialized before LEDControl.

Signed-off-by: Johannes Becker <alfalfasprossen@gmail.com>
---
 src/kaleidoscope/plugin/LEDControl.cpp | 23 +++++++++++++++++++----
 src/kaleidoscope/plugin/LEDControl.h   |  1 +
 2 files changed, 20 insertions(+), 4 deletions(-)

diff --git a/src/kaleidoscope/plugin/LEDControl.cpp b/src/kaleidoscope/plugin/LEDControl.cpp
index c43a8cca..92a62c9d 100644
--- a/src/kaleidoscope/plugin/LEDControl.cpp
+++ b/src/kaleidoscope/plugin/LEDControl.cpp
@@ -32,6 +32,7 @@ LEDMode *LEDControl::cur_led_mode_;
 uint8_t LEDControl::syncDelay = 32;
 uint16_t LEDControl::syncTimer = 0;
 bool LEDControl::enabled_ = true;
+Key LEDControl::pending_next_prev_key_ = Key_NoKey;
 
 LEDControl::LEDControl(void) {
 }
@@ -155,10 +156,10 @@ kaleidoscope::EventHandlerResult LEDControl::onKeyswitchEvent(Key &mappedKey, Ke
     return kaleidoscope::EventHandlerResult::OK;
 
   if (keyToggledOn(keyState)) {
-    if (mappedKey == Key_LEDEffectNext) {
-      next_mode();
-    } else if (mappedKey == Key_LEDEffectPrevious) {
-      prev_mode();
+    if (mappedKey == Key_LEDEffectNext || mappedKey == Key_LEDEffectPrevious) {
+      // Handling of these keys is delayed into `beforeReportingState`
+      // so that we can incorporate the shift modifier state.
+      pending_next_prev_key_ = mappedKey;
     } else if (mappedKey == Key_LEDToggle) {
       if (enabled_)
         disable();
@@ -174,6 +175,20 @@ kaleidoscope::EventHandlerResult LEDControl::beforeReportingState(void) {
   if (!enabled_)
     return kaleidoscope::EventHandlerResult::OK;
 
+  if (pending_next_prev_key_ != Key_NoKey) {
+    bool is_shifted =
+        kaleidoscope::Runtime.hid().keyboard().isModifierKeyActive(Key_LeftShift) ||
+        kaleidoscope::Runtime.hid().keyboard().isModifierKeyActive(Key_RightShift);
+
+    if ((pending_next_prev_key_ == Key_LEDEffectNext && !is_shifted) ||
+        (pending_next_prev_key_ == Key_LEDEffectPrevious && is_shifted)) {
+      next_mode();
+    } else {
+      prev_mode();
+    }
+    pending_next_prev_key_ = Key_NoKey;
+  }
+
   if (Runtime.hasTimeExpired(syncTimer, syncDelay)) {
     syncLeds();
     syncTimer += syncDelay;
diff --git a/src/kaleidoscope/plugin/LEDControl.h b/src/kaleidoscope/plugin/LEDControl.h
index 123147a9..e416f1c8 100644
--- a/src/kaleidoscope/plugin/LEDControl.h
+++ b/src/kaleidoscope/plugin/LEDControl.h
@@ -161,6 +161,7 @@ class LEDControl : public kaleidoscope::Plugin {
   static uint8_t num_led_modes_;
   static LEDMode *cur_led_mode_;
   static bool enabled_;
+  static Key pending_next_prev_key_;
 };
 
 class FocusLEDCommand : public Plugin {

From e9f03ddd5b7f98e4c858233f61ddd8769484c902 Mon Sep 17 00:00:00 2001
From: Jesse Vincent <jesse@keyboard.io>
Date: Sun, 7 Jun 2020 23:39:56 -0700
Subject: [PATCH 03/15] Remove the term 'blacklist' from an example in the
 coding style guide

---
 docs/codebase/code-style.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/codebase/code-style.md b/docs/codebase/code-style.md
index 7e6b2402..e8fc479d 100644
--- a/docs/codebase/code-style.md
+++ b/docs/codebase/code-style.md
@@ -2535,10 +2535,10 @@ auto x_plus_n = [&x](int n) -> int { return x + n; }
 Short lambdas may be written inline as function arguments.
 
 ```c++
-std::set<int> blacklist = {7, 8, 9};
+std::set<int> skip_list = {7, 8, 9};
 std::vector<int> digits = {3, 9, 1, 8, 4, 7, 1};
-digits.erase(std::remove_if(digits.begin(), digits.end(), [&blacklist](int i) {
-               return blacklist.find(i) != blacklist.end();
+digits.erase(std::remove_if(digits.begin(), digits.end(), [&skip_list](int i) {
+               return skip_list.find(i) != skip_list.end();
              }),
              digits.end());
 ```

From 16e3324e28f68f7418048af922ee382b877bf437 Mon Sep 17 00:00:00 2001
From: Jesse Vincent <jesse@keyboard.io>
Date: Sun, 7 Jun 2020 23:43:25 -0700
Subject: [PATCH 04/15] astyle

Signed-off-by: Jesse Vincent <jesse@keyboard.io>
---
 src/kaleidoscope/plugin/LEDControl.cpp | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/kaleidoscope/plugin/LEDControl.cpp b/src/kaleidoscope/plugin/LEDControl.cpp
index 92a62c9d..61d2dfc2 100644
--- a/src/kaleidoscope/plugin/LEDControl.cpp
+++ b/src/kaleidoscope/plugin/LEDControl.cpp
@@ -177,8 +177,8 @@ kaleidoscope::EventHandlerResult LEDControl::beforeReportingState(void) {
 
   if (pending_next_prev_key_ != Key_NoKey) {
     bool is_shifted =
-        kaleidoscope::Runtime.hid().keyboard().isModifierKeyActive(Key_LeftShift) ||
-        kaleidoscope::Runtime.hid().keyboard().isModifierKeyActive(Key_RightShift);
+      kaleidoscope::Runtime.hid().keyboard().isModifierKeyActive(Key_LeftShift) ||
+      kaleidoscope::Runtime.hid().keyboard().isModifierKeyActive(Key_RightShift);
 
     if ((pending_next_prev_key_ == Key_LEDEffectNext && !is_shifted) ||
         (pending_next_prev_key_ == Key_LEDEffectPrevious && is_shifted)) {

From b83d191866833069e5e1f9d2a5e7242d699a181c Mon Sep 17 00:00:00 2001
From: Jesse Vincent <jesse@keyboard.io>
Date: Mon, 8 Jun 2020 16:39:18 -0700
Subject: [PATCH 05/15] MINIMAL renaming to get the device to show up as the
 Keyboardio Atreus in Examples and in the boards manager.

This is not the final step, but should be enough that users won't get bitten later
---
 examples/Devices/Keyboardio/Atreus/.kaleidoscope-builder.conf   | 2 ++
 .../Atreus2/Atreus2.ino => Keyboardio/Atreus/Atreus.ino}        | 0
 .../Devices/{Technomancy/Atreus2 => Keyboardio/Atreus}/Makefile | 0
 examples/Devices/Technomancy/Atreus2/.kaleidoscope-builder.conf | 2 --
 ...ancy-Atreus2.h => Kaleidoscope-Hardware-Keyboardio-Atreus.h} | 0
 src/kaleidoscope/device/technomancy/Atreus2.cpp                 | 2 +-
 src/kaleidoscope/device/technomancy/Atreus2.h                   | 2 +-
 7 files changed, 4 insertions(+), 4 deletions(-)
 create mode 100644 examples/Devices/Keyboardio/Atreus/.kaleidoscope-builder.conf
 rename examples/Devices/{Technomancy/Atreus2/Atreus2.ino => Keyboardio/Atreus/Atreus.ino} (100%)
 rename examples/Devices/{Technomancy/Atreus2 => Keyboardio/Atreus}/Makefile (100%)
 delete mode 100644 examples/Devices/Technomancy/Atreus2/.kaleidoscope-builder.conf
 rename src/{Kaleidoscope-Hardware-Technomancy-Atreus2.h => Kaleidoscope-Hardware-Keyboardio-Atreus.h} (100%)

diff --git a/examples/Devices/Keyboardio/Atreus/.kaleidoscope-builder.conf b/examples/Devices/Keyboardio/Atreus/.kaleidoscope-builder.conf
new file mode 100644
index 00000000..5d03ea41
--- /dev/null
+++ b/examples/Devices/Keyboardio/Atreus/.kaleidoscope-builder.conf
@@ -0,0 +1,2 @@
+DEFAULT_SKETCH="Atreus"
+BOARD="keyboardio_atreus"
diff --git a/examples/Devices/Technomancy/Atreus2/Atreus2.ino b/examples/Devices/Keyboardio/Atreus/Atreus.ino
similarity index 100%
rename from examples/Devices/Technomancy/Atreus2/Atreus2.ino
rename to examples/Devices/Keyboardio/Atreus/Atreus.ino
diff --git a/examples/Devices/Technomancy/Atreus2/Makefile b/examples/Devices/Keyboardio/Atreus/Makefile
similarity index 100%
rename from examples/Devices/Technomancy/Atreus2/Makefile
rename to examples/Devices/Keyboardio/Atreus/Makefile
diff --git a/examples/Devices/Technomancy/Atreus2/.kaleidoscope-builder.conf b/examples/Devices/Technomancy/Atreus2/.kaleidoscope-builder.conf
deleted file mode 100644
index b0bcc80e..00000000
--- a/examples/Devices/Technomancy/Atreus2/.kaleidoscope-builder.conf
+++ /dev/null
@@ -1,2 +0,0 @@
-DEFAULT_SKETCH="Atreus2"
-BOARD="atreus2"
diff --git a/src/Kaleidoscope-Hardware-Technomancy-Atreus2.h b/src/Kaleidoscope-Hardware-Keyboardio-Atreus.h
similarity index 100%
rename from src/Kaleidoscope-Hardware-Technomancy-Atreus2.h
rename to src/Kaleidoscope-Hardware-Keyboardio-Atreus.h
diff --git a/src/kaleidoscope/device/technomancy/Atreus2.cpp b/src/kaleidoscope/device/technomancy/Atreus2.cpp
index 2a4423f2..427bc670 100644
--- a/src/kaleidoscope/device/technomancy/Atreus2.cpp
+++ b/src/kaleidoscope/device/technomancy/Atreus2.cpp
@@ -17,7 +17,7 @@
  */
 
 #ifndef KALEIDOSCOPE_VIRTUAL_BUILD
-#ifdef ARDUINO_AVR_ATREUS2
+#ifdef ARDUINO_AVR_KEYBOARDIO_ATREUS
 
 #include "kaleidoscope/Runtime.h"
 #include "kaleidoscope/driver/keyscanner/Base_Impl.h"
diff --git a/src/kaleidoscope/device/technomancy/Atreus2.h b/src/kaleidoscope/device/technomancy/Atreus2.h
index 2cc0a222..0f78c134 100644
--- a/src/kaleidoscope/device/technomancy/Atreus2.h
+++ b/src/kaleidoscope/device/technomancy/Atreus2.h
@@ -18,7 +18,7 @@
 
 #pragma once
 
-#ifdef ARDUINO_AVR_ATREUS2
+#ifdef ARDUINO_AVR_KEYBOARDIO_ATREUS
 
 #include <Arduino.h>
 

From a2a419273008e515105868560f4d3cc23b9beab2 Mon Sep 17 00:00:00 2001
From: Jesse Vincent <jesse@keyboard.io>
Date: Mon, 8 Jun 2020 16:53:02 -0700
Subject: [PATCH 06/15] Begin to rename Technomancy Atreus2 to Keyboardio
 Atreus

---
 src/kaleidoscope/device/technomancy/Atreus2.cpp | 4 ++--
 src/kaleidoscope/device/technomancy/Atreus2.h   | 8 ++++----
 2 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/src/kaleidoscope/device/technomancy/Atreus2.cpp b/src/kaleidoscope/device/technomancy/Atreus2.cpp
index 427bc670..f4471f61 100644
--- a/src/kaleidoscope/device/technomancy/Atreus2.cpp
+++ b/src/kaleidoscope/device/technomancy/Atreus2.cpp
@@ -24,7 +24,7 @@
 
 namespace kaleidoscope {
 namespace device {
-namespace technomancy {
+namespace keyboardio {
 
 ATMEGA_KEYSCANNER_BOILERPLATE
 
@@ -32,7 +32,7 @@ ATMEGA_KEYSCANNER_BOILERPLATE
 }
 }
 
-kaleidoscope::device::technomancy::Atreus2 &Atreus2 = kaleidoscope_internal::device;
+kaleidoscope::device::keyboardio::Atreus &Atreus = kaleidoscope_internal::device;
 
 #endif
 #endif // ifndef KALEIDOSCOPE_VIRTUAL_BUILD
diff --git a/src/kaleidoscope/device/technomancy/Atreus2.h b/src/kaleidoscope/device/technomancy/Atreus2.h
index 0f78c134..95071880 100644
--- a/src/kaleidoscope/device/technomancy/Atreus2.h
+++ b/src/kaleidoscope/device/technomancy/Atreus2.h
@@ -27,10 +27,10 @@
 
 namespace kaleidoscope {
 namespace device {
-namespace technomancy {
+namespace keyboardio {
 
 ATMEGA32U4_KEYBOARD(
-  Atreus2, Caterina, "atreus",
+  Atreus, Caterina, "atreus",
   ROW_PIN_LIST({PIN_F6, PIN_F5, PIN_F4, PIN_F1}),
   COL_PIN_LIST({PIN_F7, PIN_E2, PIN_C7, PIN_C6, PIN_B6, PIN_B5, PIN_D7, PIN_D6, PIN_D4, PIN_D5, PIN_D3, PIN_D2})
 );
@@ -64,10 +64,10 @@ ATMEGA32U4_KEYBOARD(
 }
 }
 
-EXPORT_DEVICE(kaleidoscope::device::technomancy::Atreus2)
+EXPORT_DEVICE(kaleidoscope::device::keyboardio::Atreus)
 
 }
 
-extern kaleidoscope::device::technomancy::Atreus2 DEPRECATED(NAMED_HARDWARE) &Atreus2;
+extern kaleidoscope::device::keyboardio::Atreus DEPRECATED(NAMED_HARDWARE) &Atreus;
 
 #endif

From cc62dbae734bb725c9e12ce15134aa9de3c8236e Mon Sep 17 00:00:00 2001
From: Jesse Vincent <jesse@keyboard.io>
Date: Mon, 8 Jun 2020 16:58:39 -0700
Subject: [PATCH 07/15] Next step of renaming the Technomancy Atreus2 to the
 Keyboardio Atreus

---
 src/Kaleidoscope-Hardware-Keyboardio-Atreus.h                   | 2 +-
 src/kaleidoscope/device/{technomancy => keyboardio}/Atreus2.cpp | 0
 src/kaleidoscope/device/{technomancy => keyboardio}/Atreus2.h   | 0
 3 files changed, 1 insertion(+), 1 deletion(-)
 rename src/kaleidoscope/device/{technomancy => keyboardio}/Atreus2.cpp (100%)
 rename src/kaleidoscope/device/{technomancy => keyboardio}/Atreus2.h (100%)

diff --git a/src/Kaleidoscope-Hardware-Keyboardio-Atreus.h b/src/Kaleidoscope-Hardware-Keyboardio-Atreus.h
index 1416d6d5..46d0bd83 100644
--- a/src/Kaleidoscope-Hardware-Keyboardio-Atreus.h
+++ b/src/Kaleidoscope-Hardware-Keyboardio-Atreus.h
@@ -18,4 +18,4 @@
 
 #pragma once
 
-#include "kaleidoscope/device/technomancy/Atreus2.h"
+#include "kaleidoscope/device/keyboardio/Atreus2.h"
diff --git a/src/kaleidoscope/device/technomancy/Atreus2.cpp b/src/kaleidoscope/device/keyboardio/Atreus2.cpp
similarity index 100%
rename from src/kaleidoscope/device/technomancy/Atreus2.cpp
rename to src/kaleidoscope/device/keyboardio/Atreus2.cpp
diff --git a/src/kaleidoscope/device/technomancy/Atreus2.h b/src/kaleidoscope/device/keyboardio/Atreus2.h
similarity index 100%
rename from src/kaleidoscope/device/technomancy/Atreus2.h
rename to src/kaleidoscope/device/keyboardio/Atreus2.h

From 0a103d156894df4607e1792717227681c07c2990 Mon Sep 17 00:00:00 2001
From: Jesse Vincent <jesse@keyboard.io>
Date: Mon, 8 Jun 2020 20:11:01 -0700
Subject: [PATCH 08/15] Comments cleanup for the Atreus port

---
 examples/Devices/Keyboardio/Atreus/Atreus.ino  | 2 +-
 src/Kaleidoscope-Hardware-Keyboardio-Atreus.h  | 2 +-
 src/kaleidoscope/device/keyboardio/Atreus2.cpp | 2 +-
 src/kaleidoscope/device/keyboardio/Atreus2.h   | 2 +-
 4 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/examples/Devices/Keyboardio/Atreus/Atreus.ino b/examples/Devices/Keyboardio/Atreus/Atreus.ino
index 41f33d14..aa1445ff 100644
--- a/examples/Devices/Keyboardio/Atreus/Atreus.ino
+++ b/examples/Devices/Keyboardio/Atreus/Atreus.ino
@@ -1,5 +1,5 @@
 /* -*- mode: c++ -*-
- * Atreus -- Chrysalis-enabled Sketch for the Atreus2
+ * Atreus -- Chrysalis-enabled Sketch for the Keyboardio Atreus
  * Copyright (C) 2018, 2019  Keyboard.io, Inc
  *
  * This program is free software; you can redistribute it and/or modify
diff --git a/src/Kaleidoscope-Hardware-Keyboardio-Atreus.h b/src/Kaleidoscope-Hardware-Keyboardio-Atreus.h
index 46d0bd83..32642c6c 100644
--- a/src/Kaleidoscope-Hardware-Keyboardio-Atreus.h
+++ b/src/Kaleidoscope-Hardware-Keyboardio-Atreus.h
@@ -1,5 +1,5 @@
 /* -*- mode: c++ -*-
- * Kaleidoscope-Hardware-Technomancy-Atreus2 -- Atreus2 hardware support for Kaleidoscope
+ * Kaleidoscope-Hardware-Keyboardio-Atreus -- Keyboardio Atreus hardware support for Kaleidoscope
  * Copyright (C) 2019  Keyboard.io, Inc
  *
  * This program is free software: you can redistribute it and/or modify
diff --git a/src/kaleidoscope/device/keyboardio/Atreus2.cpp b/src/kaleidoscope/device/keyboardio/Atreus2.cpp
index f4471f61..24f05e64 100644
--- a/src/kaleidoscope/device/keyboardio/Atreus2.cpp
+++ b/src/kaleidoscope/device/keyboardio/Atreus2.cpp
@@ -1,5 +1,5 @@
 /* -*- mode: c++ -*-
- * Technomancy Atreus2 hardware support for Kaleidoscope
+ * Keyboardio Atreus hardware support for Kaleidoscope
  * Copyright (C) 2019  Keyboard.io, Inc
  *
  * This program is free software: you can redistribute it and/or modify
diff --git a/src/kaleidoscope/device/keyboardio/Atreus2.h b/src/kaleidoscope/device/keyboardio/Atreus2.h
index 95071880..57a924f0 100644
--- a/src/kaleidoscope/device/keyboardio/Atreus2.h
+++ b/src/kaleidoscope/device/keyboardio/Atreus2.h
@@ -1,5 +1,5 @@
 /* -*- mode: c++ -*-
- * Technomancy Atreus2 hardware support for Kaleidoscope
+ * Keyboardio Atreus hardware support for Kaleidoscope
  * Copyright (C) 2019  Keyboard.io, Inc
  *
  * This program is free software: you can redistribute it and/or modify

From ca06492a896869e57a631dabb47aff735372e3e3 Mon Sep 17 00:00:00 2001
From: Jesse Vincent <jesse@keyboard.io>
Date: Mon, 8 Jun 2020 22:21:08 -0700
Subject: [PATCH 09/15] Add a "design philosophy" doc migrated from the wiki

---
 docs/codebase/design-philosophy.md | 9 +++++++++
 docs/index.rst                     | 3 ++-
 2 files changed, 11 insertions(+), 1 deletion(-)
 create mode 100644 docs/codebase/design-philosophy.md

diff --git a/docs/codebase/design-philosophy.md b/docs/codebase/design-philosophy.md
new file mode 100644
index 00000000..a5785752
--- /dev/null
+++ b/docs/codebase/design-philosophy.md
@@ -0,0 +1,9 @@
+Kaleidoscope should, in order:  
+
+1) Work well as a keyboard 
+2) Be compatible with real hardware 
+3) Be compatible with the spec 
+4) Be easy to read and understand 
+5) Be easy to modify and customize
+
+Our code indentation style is managed with 'make astyle.' For code we 'own', there should be an astyle target in the Makefile. For third party code we use and expect to update (ever), we try not to mess with the upstream house style.
diff --git a/docs/index.rst b/docs/index.rst
index 8192582b..b51137b1 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -51,7 +51,8 @@ Understanding the codebase
 
 .. toctree::
    :maxdepth: 1
-
+  
+   codebase/design-philosophy.md
    codebase/glossary.md
    codebase/code-style.md
 

From 1472af7ba80cca64ca1624067609a7d8de5c8f96 Mon Sep 17 00:00:00 2001
From: Jesse Vincent <jesse@keyboard.io>
Date: Mon, 8 Jun 2020 22:27:25 -0700
Subject: [PATCH 10/15] Migrate "release testing" from the wiki

---
 docs/codebase/release-testing.md | 97 ++++++++++++++++++++++++++++++++
 docs/index.rst                   |  1 +
 2 files changed, 98 insertions(+)
 create mode 100644 docs/codebase/release-testing.md

diff --git a/docs/codebase/release-testing.md b/docs/codebase/release-testing.md
new file mode 100644
index 00000000..439c3d55
--- /dev/null
+++ b/docs/codebase/release-testing.md
@@ -0,0 +1,97 @@
+# Release testing
+
+Before a new release of Kaleidoscope, the following test process should be run through on all supported operating systems.
+
+(As of August 2017, this whole thing really applies to Model01-Firmware, but we hope to generalize it to Kaleidoscope)
+
+# Tested operating systems
+
+* The latest stable Ubuntu Linux release running X11. (We _should_ eventually be testing both X11 and Wayland)
+* The latest stable release of macOS
+* An older Mac OS X release TBD. (There were major USB stack changes in 10.9 or so)
+* Windows 10
+* Windows 7
+* The current release of ChromeOS
+* A currentish android tablet that supports USB Host
+* an iOS device (once we fix the usb connection issue to limit power draw)
+
+# Test process
+
+## Basic testing
+1. Plug the keyboard in
+1. Make sure the host OS doesn't throw an error
+1. Make sure the LED in the top left doesn't glow red
+1. Make sure the LED in the top-right corner of the left side breathes blue for ~10s
+1. Bring up some sort of notepad app or text editor
+
+## Basic testing, part 2
+
+1. Test typing of shifted and unshifted letters and numbers with and without key repeat
+1. Test typing of fn-shifted characters: []{}|\ with and without key repeat
+1. Test that 'Any' key generates a random letter or number and that key repeat works
+1. Test fn-hjkl to move the cursor
+1. Test Fn-WASD to move the mouse
+1. Test Fn-RFV for the three mouse buttons
+1. Test Fn-BGTabEsc for mouse warp
+1. Test that LeftFn+RightFn + hjkl move the cursor
+1. Verify that leftfn+rightfn do not light up the numpad
+
+## NKRO
+
+1. Open the platform's native key event viewer
+   (If not available, visit https://www.microsoft.com/appliedsciences/KeyboardGhostingDemo.mspx in a browser)
+1. Press as many keys as your fingers will let you
+1. Verify that the keymap reports all the keys you're pressing
+
+
+## Test media keys
+
+1. Fn-Any: previous track
+1. Fn-Y: next-track
+1. Fn-Enter: play/pause
+1. Fn-Butterfly: Windows 'menu' key
+1. Fn-n: mute
+1. Fn-m: volume down
+1. Fn-,: volume up
+
+## Test numlock
+
+1. Tap "Num"
+1. Verify that the numpad lights up red
+1. Verify that the num key is breathing blue
+1. Verify that numpad keys generate numbers
+1. Tap the Num key
+1. Verify that the numpad keys stop being lit up
+1 Verify that 'jkl' don't generate numbers.
+
+## Test LED Effects 
+
+1. Tap the LED key
+1. Verify that there is a rainbow effect
+1. Tap the LED key a few more times and verify that other LED effects show up
+1. Verify that you can still type.
+
+## Second connection
+1. Unplug the keyboard
+1. Plug the keyboard back in
+1. Make sure you can still type
+
+## Programming
+1. If the OS has a way to show serial port devices, verify that the keyboard's serial port shows up.
+1. If you can run stty, as you can on linux and macos, make sure you can tickle the serial port at 1200 bps.
+    Linux: stty -F /dev/ttyACM0 1200
+    Mac: 
+1. If you tickle the serial port without holding down the prog key, verify that the Prog key does not light up red
+1. If you hold down the prog key before tickling the serial port, verify that the Prog key's LED lights up red.
+1. Unplug the keyboard
+1. While holding down prog, plug the keyboard in
+1. Verify that the prog key is glowing red.
+1. Unplug the keyboard
+1. Plug the keyboard in
+1. Verify that the prog key is not glowing red.
+
+# If the current platform supports the Arduino IDE (Win/Lin/Mac)
+1. use the Arduino IDE to reflash the current version of the software.
+1. Verify that you can type a few keys
+1. Verify that the LED key toggles between LED effects
+
diff --git a/docs/index.rst b/docs/index.rst
index b51137b1..96416f8b 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -55,6 +55,7 @@ Understanding the codebase
    codebase/design-philosophy.md
    codebase/glossary.md
    codebase/code-style.md
+   codebase/release-testing.md
 
 API Design docs
 ---------------

From fb8a9aa25be501b2a8b0a97f6010a5b5ce9cf67b Mon Sep 17 00:00:00 2001
From: Jesse Vincent <jesse@keyboard.io>
Date: Mon, 8 Jun 2020 22:30:38 -0700
Subject: [PATCH 11/15] Add a title for the design philosophy

---
 docs/codebase/design-philosophy.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/docs/codebase/design-philosophy.md b/docs/codebase/design-philosophy.md
index a5785752..ab301665 100644
--- a/docs/codebase/design-philosophy.md
+++ b/docs/codebase/design-philosophy.md
@@ -1,3 +1,5 @@
+# Design philosophy
+
 Kaleidoscope should, in order:  
 
 1) Work well as a keyboard 

From d63d6b8409368bdebfcc6ad7e7271c3ebb796d61 Mon Sep 17 00:00:00 2001
From: Jesse Vincent <jesse@keyboard.io>
Date: Mon, 8 Jun 2020 22:45:34 -0700
Subject: [PATCH 12/15] migrate led plugin overview from wiki

---
 docs/index.rst         |  8 ++++++++
 docs/overviews/leds.md | 37 +++++++++++++++++++++++++++++++++++++
 2 files changed, 45 insertions(+)
 create mode 100644 docs/overviews/leds.md

diff --git a/docs/index.rst b/docs/index.rst
index 96416f8b..787e49aa 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -34,6 +34,14 @@ Supported input devices
 
    hardware-devices/*
 
+Topic overviews
+----------------
+.. toctree::
+   :maxdepth: 1
+   :glob: 
+
+   overviews/*
+
 Plugins 
 -------
 .. toctree::
diff --git a/docs/overviews/leds.md b/docs/overviews/leds.md
new file mode 100644
index 00000000..7f36858b
--- /dev/null
+++ b/docs/overviews/leds.md
@@ -0,0 +1,37 @@
+# Core LED Effects
+
+
+This is the list of the stable LED effects in the core libraries.
+
+<h4>LED-ActiveModColor</h4>
+
+A very simple plugin, that lights up the LED in white under any active modifier, for the duration of its activity. Also supports one-shots.
+
+<h4>Kaleidoscope-LEDEffects</h4>
+
+The LEDEffects plugin provides a selection of LED effects, each of them fairly simple, simple enough to not need a plugin of their own. There are a number of different effects included in the package, all of them are available once including the header, and one's free to choose any number of them. 
+<h4>Kaleidoscope-LEDEffect-BootGreeting</h4>
+
+If you want to have your keyboard signal when it turns on, but you don't want to use any more complicated LED modes, this plugin is for you. It will make the ``LEDEffectNext`` key on your keymap slowly breathe for about ten seconds after plugging the keyboard in (without blocking the normal functionality of the keyboard, of course).
+
+<h4>Kaleidoscope-LEDEffect-Breathe</h4>
+
+Provides a breathing effect for the keyboard. Breathe in, breathe out.
+
+<h4>Kaleidoscope-LEDEffect-Chase</h4>
+
+A simple LED effect where one color chases another across the keyboard and back, over and over again. Playful colors they are.
+
+<h4>Kaleidoscope-LEDEffect-Rainbow</h4>
+
+Two colorful rainbow effects are implemented by this plugin: one where the rainbow waves through the keys, and another where the LEDs breathe though the colors of a rainbow. The difference is that in the first case, we have all the rainbow colors on display, and it waves through the keyboard. In the second case, we have only one color at a time, for the whole board, and the color cycles through the rainbow's palette.
+
+<h4>Kaleidoscope-LEDEffect-SolidColor</h4>
+
+This plugin provides tools to build LED effects that set the entire keyboard to a single color. For show, and for backlighting purposes.
+
+<h4>LED-Stalker</h4>
+
+Demoed in the backer update, this adds an effect that stalks your keys: whenever a key is pressed, the LED under it lights up, and the slowly fades away once the key is released. This provides a kind of trailing effect.
+
+There are two color schemes currently: Haunt, which is a white-ish, ghostly color that follows your fingers, and BlazingTrail, demoed in the video, which lights your keyboard on fire. It looks much better in real life.

From 9f5146836684f71bc54ee8d2c9cb8c2def2bae2d Mon Sep 17 00:00:00 2001
From: Jesse Vincent <jesse@keyboard.io>
Date: Mon, 8 Jun 2020 23:01:29 -0700
Subject: [PATCH 13/15] Migrate
 https://github.com/keyboardio/Kaleidoscope/wiki/EEPROM-Customizing-Without-Programming
 from wiki

---
 docs/overviews/eeprom.md | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)
 create mode 100644 docs/overviews/eeprom.md

diff --git a/docs/overviews/eeprom.md b/docs/overviews/eeprom.md
new file mode 100644
index 00000000..e164979e
--- /dev/null
+++ b/docs/overviews/eeprom.md
@@ -0,0 +1,29 @@
+# Using EEPROM
+
+## Why Use EEPROM?
+
+While we've done our best to make it easy to change how your keyboard works by changing your firmware & re-flashing it, sometimes it would be convenient to be able to make changes without having to go through that rigamarole.
+Maybe you'd like to be able to use a GUI like [Chrysalis](https://github.com/keyboardio/Chrysalis) to configure your keyboard layout or LED themes, or maybe your sketch is getting very complicated and you're looking for a way to save program memory.
+In either case, you'll want to use EEPROM to store your settings.
+
+## What is EEPROM?
+
+EEPROM stands for "Electronic Erasable Programmable Read-Only Memory" and is one of the three memory mediums your keyboard has.
+The other two are RAM, which is used for variables when running your code, and program memory, which is used for storing the program, as well as some other select pieces of data (if you're curious, the bit in your sketch where it says `PROGMEM` indicates that a variable is being stored in program memory instead of RAM).
+RAM we want to keep as free as we can, since running our code will need some RAM to work.
+While we can put stuff in PROGMEM, your code itself will take up some room there, so it may be useful to store things elsewhere.
+EEPROM provides us with another place to store things that can free up RAM and PROGMEM.
+Additionally, by leveraging a few plugins, we can store configuration in EEPROM and allow a GUI tool on the connected computer to change settings on the keyboard!
+
+## Move Settings to EEPROM
+
+There are a few important Kaleidoscope plugins for putting settings in EEPROM:
+
+  <!-- - [Kaleidoscope-EEPROM-Keymap-Programmer][] - is this worth mentioning in this context? -->
+  - Kaleidoscope-Focus] - This plugin is what enables communication between your keyboard and programs running on your computer; all the following plugins require you to be using this if you want to be able to change your settings from the computer without re-flashing.
+  - Kaleidoscope-EEPROM-Settings - This is a plugin that doesn't do much by itself, but most of the other EEPROM plugins will need active to be able to make use of EEPROM storage.
+  - Kaleidoscope-EEPROM-Keymap - This plugin uses Focus and EEPROM-Settings to allow either overriding or fully replacing the programmed-in keymap without reflashing (by means of a program like Chrysalis running on your computer).
+  - Kaleidoscope-Colormap - This plugin allows you to use a computer-side program to set a (static -- i.e. the keys won't change colour over time) LED theme for each layer.
+
+All these plugins have minimal installation that can be found in their respective READMEs.
+After following the instructions for each and adding them together, you should be able to download a program that knows how to communicate with the keyboard (i.e. [Chrysalis](https://github.com/keyboardio/Chrysalis) and you can start customizing settings without having to do any more programming!

From f690d5396665963dfb24ab3f28969618a8afda87 Mon Sep 17 00:00:00 2001
From: Jesse Vincent <jesse@keyboard.io>
Date: Mon, 8 Jun 2020 23:10:35 -0700
Subject: [PATCH 14/15] Migrating interdependent-plugins.md from the wiki

---
 docs/development/interdependent-plugins.md | 35 ++++++++++++++++++++++
 docs/index.rst                             |  9 ++++++
 2 files changed, 44 insertions(+)
 create mode 100644 docs/development/interdependent-plugins.md

diff --git a/docs/development/interdependent-plugins.md b/docs/development/interdependent-plugins.md
new file mode 100644
index 00000000..5f78df79
--- /dev/null
+++ b/docs/development/interdependent-plugins.md
@@ -0,0 +1,35 @@
+# Developing interdependent plugins
+
+Say you have two Kaleidoscope plugins or, more general, two Arduino libraries `A` and `B`. Let's assume `B` depends on `A` in a sense that `B` references symbols (functions/variables) defined in `A`. Both libraries define header files `a_header.h` and `b_header.h` that specify their exported symbols.
+
+The following sketch builds as expected.
+```cpp
+// my_sketch.ino
+#include "b_header.h"
+#include "a_header.h"
+...
+```
+
+If the header appear in opposite order the linker will throw undefined symbol errors regarding missing symbols from `A`.
+```cpp
+// my_sketch.ino
+#include "a_header.h"
+#include "b_header.h"
+...
+```
+The reason for this somewhat unexpected behavior is that the order of libraries' occurrence in the linker command line is crucial. The linker must see library `B` first to determine which symbols it needs to extract from `A`. If it encounters `A` first, it completely neglects its symbols as there are no references to it at that point.
+
+To be on the safe side and only if the sketch does not reference symbols from `A` directly, it is better to include the headers in the following way.
+```cpp
+// header_b.h
+#include "header_a.h"
+...
+```
+
+```cpp
+// my_sketch.ino
+// Do not include a_header.h directly. It is already included by b_header.h.
+#include "b_header.h"
+...
+```
+Note: I did no thorough research on how Arduino internally establishes the linker command line, e.g. with respect to a recursive traversal of the include-tree. This means, I am not sure how the link command line order is generated when header files that are included by the main `.ino` do include other files that provide definitions of library symbols in different orders. There might be additional pitfalls when header includes are more complex given a larger project.
diff --git a/docs/index.rst b/docs/index.rst
index 787e49aa..0e37dfc9 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -84,6 +84,15 @@ Device drivers
    drivers/**
 
 
+Development tips
+----------------
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   development/**
+
+
 What's new in v2.0
 ------------------
 .. toctree::

From 7c5988f1f3af90e8b52670ea877291152ef9154c Mon Sep 17 00:00:00 2001
From: Jesse Vincent <jesse@keyboard.io>
Date: Mon, 8 Jun 2020 23:57:26 -0700
Subject: [PATCH 15/15] Migrate
 https://github.com/keyboardio/Kaleidoscope/wiki/Core-Plugins

---
 docs/overviews/core-plugins.md | 110 +++++++++++++++++++++++++++++++++
 1 file changed, 110 insertions(+)
 create mode 100644 docs/overviews/core-plugins.md

diff --git a/docs/overviews/core-plugins.md b/docs/overviews/core-plugins.md
new file mode 100644
index 00000000..a133dee3
--- /dev/null
+++ b/docs/overviews/core-plugins.md
@@ -0,0 +1,110 @@
+# Core plugin overview
+
+This is a list of the stable core plugins. Noncore plugins can be found at https://community.keyboard.io/c/programming/Discuss-Kaleidoscope-Plugins-one-thread-per-plugin
+
+\<h4>Kaleidoscope-EEPROM-Keymap</h4>
+
+[Kaleidoscope-EEPROM-Keymap Documentation](https://github.com/keyboardio/Kaleidoscope/blob/master/docs/plugins/EEPROM-Keymap.md)
+
+While keyboards usually ship with a keymap programmed in, to be able to change that keymap, without flashing new firmware, we need a way to place the keymap into a place we can update at run-time, and which persists across reboots. Fortunately, we have a bit of EEPROM on the keyboard, and can use it to store either the full keymap (and saving space in the firmware then), or store an overlay there. In the latter case, whenever there is a non-transparent key on the overlay, we will use that instead of the keyboard default.
+
+In short, this plugin allows us to change our keymaps, without having to compile and flash new firmware. It does so through the use of the Focus plugin.
+
+<h4>Kaleidoscope-Escape-OneShot</h4>
+
+[Kaleidoscope-Escape-OneShot Documentation](https://github.com/keyboardio/Kaleidoscope/blob/master/docs/plugins/Escape-OneShot.md)
+
+Turn the Esc key into a special key, that can cancel any active OneShot effect - or act as the normal Esc key if none are active. For those times when one accidentally presses a one-shot key, or change their minds.
+
+<h4>Kaleidoscope-KeyLogger</h4>
+
+[Kaleidoscope-KeyLogger Documentation](https://github.com/keyboardio/Kaleidoscope/blob/master/docs/plugins/KeyLogger.md)
+
+The KeyLogger plugin, as the name suggests, implements a key logger for the Kaleidoscope firmware. It logs the row and column of every key press and release, along with the event, and the layer number, in a format that is reasonably easy to parse, to the Serial interface.
+
+**A word of warning**: Having a key logger is as dangerous as it sounds. Anyone who can read the serial events from the keyboard, will know exactly what keys you press, and when. Unless you know what you are doing, and can secure your keyboard, do not enable this plugin.
+
+<h4>Kaleidoscope-Leader</h4>
+
+[Kaleidoscope-Leader Documentation](https://github.com/keyboardio/Kaleidoscope/blob/master/docs/plugins/Leader.md)
+
+Leader keys are a kind of key where when they are tapped, all following keys are swallowed, until the plugin finds a matching sequence in the dictionary, it times out, or fails to find any possibilities. When a sequence is found, the corresponding action is executed, but the processing still continues. If any key is pressed that is not the continuation of the existing sequence, processing aborts, and the key is handled normally.
+
+This behaviour is best described with an example. Suppose we want a behaviour where ``LEAD u`` starts unicode input mode, and ``LEAD u h e a r t`` should result in a heart symbol being input, and we want ``LEAD u 0 0 e 9 SPC`` to input é, and any other hex code that follows ``LEAD u``, should be handled as-is, and passed to the host. Obviously, we can't have all of this in a dictionary.
+
+So we put ``LEAD u`` and ``LEAD u h e a r t`` in the dictionary only. The first will start unicode input mode, the second will type in the magic sequence that results in the symbol, and then aborts the leader sequence processing. With this setup, if we type ``LEAD u 0``, then ``LEAD u`` will be handled first, and start unicode input mode. Then, at the 0, the plugin notices it is not part of any sequence, so aborts leader processing, and passes the key on as-is, and it ends up being sent to the host. Thus, we covered all the cases of our scenario!
+
+<h4>Kaleidoscope-Macros</h4>
+
+[Kaleidoscope-Macros Documentation](https://github.com/keyboardio/Kaleidoscope/blob/master/docs/plugins/Macros.md)
+
+Macros are a standard feature on many keyboards and Kaleidoscope-powered ones are no exceptions. Macros are a way to have a single key-press do a whole lot of things under the hood: conventionally, macros play back a key sequence, but with Kaleidoscope, there is much more we can do. Nevertheless, playing back a sequence of events is still the primary use of macros.
+
+Playing back a sequence means that when we press a macro key, we can have it play pretty much any sequence. It can type some text for us, or invoke a complicated shortcut - the possibilities are endless!
+
+<h4>Kaleidoscope-MagicCombo</h4>
+
+[Kaleidoscope-MagicCombo Documentation](https://github.com/keyboardio/Kaleidoscope/blob/master/docs/plugins/MagicCombo.md)
+
+The MagicCombo extension provides a way to perform custom actions when a particular set of keys are held down together. The functionality assigned to these keys are not changed, and the custom action triggers as long as all keys within the set are pressed. The order in which they were pressed do not matter.
+
+This can be used to tie complex actions to key chords.
+
+<h4>Kaleidoscope-OneShot</h4>
+
+[Kaleidoscope-OneShot Documentation](https://github.com/keyboardio/Kaleidoscope/blob/master/docs/plugins/OneShot.md)
+
+One-shots are a new kind of behaviour for your standard modifier and momentary layer keys: instead of having to hold them while pressing other keys, they can be tapped and released, and will remain active until any other key is pressed. In short, they turn ``Shift, A`` into ``Shift+A``, and ``Fn, 1`` to ``Fn+1``. The main advantage is that this allows us to place the modifiers and layer keys to positions that would otherwise be awkward when chording. Nevertheless, they still act as normal when held, that behaviour is not lost.
+
+Furthermore, if a one-shot key is tapped two times in quick succession, it becomes sticky, and remains active until disabled with a third tap. This can be useful when one needs to input a number of keys with the modifier or layer active, and still does not wish to hold the key down. If this feature is undesirable, unset the ``OneShot.double_tap_sticky property`` (see later).
+
+To make multi-modifier, or multi-layer shortcuts possible, one-shot keys remain active if another one-shot of the same type is tapped, so ``Ctrl, Alt, b`` becomes ``Ctrl+Alt+b``, and ``L1, L2, c`` is turned into ``L1+L2+c``.
+
+<h4>Kaleidoscope-ShapeShifter</h4>
+
+[Kaleidoscope-ShapeShifter Documentation](https://github.com/keyboardio/Kaleidoscope/blob/master/docs/plugins/ShapeShifter.md)
+
+ShapeShifter is a plugin that makes it considerably easier to change what symbol is input when a key is pressed together with ``Shift``. If one wants to rearrange the symbols on the number row for example, without modifying the layout on the operating system side, this plugin is where one can turn to.
+
+What it does, is very simple: if any key in its dictionary is found pressed while ``Shift`` is held, it will press another key instead of the one triggering the event. For example, if it sees ``Shift + 1`` pressed together, which normally results in a ``!``, it will press ``4`` instead of ``1``, inputting ``$``.
+
+<h4>Kaleidoscope-SpaceCadet</h4>
+
+[Kaleidoscope-SpaceCadet Documentation](https://github.com/keyboardio/Kaleidoscope/blob/master/docs/plugins/SpaceCadet.md)
+
+Space Cadet is a way to make it more convenient to input parens - those ``(`` and ``)`` things -, symbols that a lot of programming languages use frequently. If you are working with Lisp, you are using these all the time.
+
+What it does, is that it turns your left and right ``Shift`` keys into parens if you tap and release them, without pressing any other key while holding them. Therefore, to input, say, ``(print foo)``, you don't need to press ``Shift``, hold it, and press ``9`` to get a ``(``, you simply press and release ``Shift``, and continue writing. You use it as if you had a dedicated key for parens!
+
+But if you wish to write capital letters, you hold it, as usual, and you will not see any parens when you release it. You can also hold it for a longer time, and it still would act as a ``Shift``, without the parens inserted on release: this is useful when you want to augment some mouse action with ``Shift``, to select text, for example.
+
+After getting used to the Space Cadet style of typing, you may wish to enable this sort of functionality on other keys, as well. Fortunately, the Space Cadet plugin is configurable and extensible to support adding symbols to other keys. Along with ``(`` on your left ``Shift`` key and ``)`` on your right ``Shift`` key, you may wish to add other such programming mainstays as ``{`` to your left-side ``cmd`` key, ``}`` to your right-side ``alt`` key, [ to your left ``Control`` key, and ``]`` to your right ``Control`` key. You can map the keys in whatever way you may wish to do, so feel free to experiment with different combinations and discover what works best for you!
+
+<h4>Kaleidoscope-TapDance</h4>
+
+[Kaleidoscope-TapDance Documentation](https://github.com/keyboardio/Kaleidoscope/blob/master/docs/plugins/TapDance.md)
+
+Tap-dance keys are general purpose, multi-use keys, which trigger a different action based on the number of times they were tapped in sequence. As an example to make this clearer, one can have a key that inputs ``A`` when tapped once, inputs ``B`` when tapped twice, and lights up the keyboard in Christmas colors when tapped a third time.
+
+This behaviour is most useful in cases where we have a number of things we perform rarely, where tapping a single key repeatedly is not counter-productive. Such cases include - for example - multimedia forward / backward keys: forward on single tap, backward on double. Of course, one could use modifiers to achieve a similar effect, but that's two keys to use, this is only one. We can also hide some destructive functionality behind a number of taps: reset the keyboard after 4 taps, and light up LEDs in increasingly frightful colors until then.
+
+How does it work?
+
+To not interfere with normal typing, tap-dance keys have two ways to decide when to call an action: they either get interrupted, or they time out. Every time a tap-dance key is pressed, the timer resets, so one does not have to finish the whole tapping sequence within a short time limit. The tap-dance counter continues incrementing until one of these cases happen.
+
+When a tap-dance key is pressed and released, and nothing is pressed on the keyboard until the timeout is reached, then the key will time out, and trigger an action. Which action, depends on the number of times it has been tapped up until this point.
+
+When a tap-dance key is pressed and released, and another key is hit before the timer expires, then the tap-dance key will trigger an action first, perform it, and only then will the firmware continue handling the interrupting key press. This is to preserve the order of keys pressed.
+
+In both of these cases, the ``tapDanceAction`` will be called, with ``tapDanceIndex`` set to the index of the tap-dance action (as set in the keymap), the ``tapCount``, and tapDanceAction set to either ``kaleidoscope::TapDance::Interrupt``, or ``kaleidoscope::TapDance::Timeout``. If we continue holding the key, then as long as it is held, the same function will be called with tapDanceAction set to ``kaleidoscope::TapDance::Hold``. When the key is released, after either an Interrupt or Timeout action was triggered, the function will be called with tapDanceAction set to ``kaleidoscope::TapDance::Release``.
+
+These actions allow us to create sophisticated tap-dance setups, where one can tap a key twice and hold it, and have it repeat, for example.
+
+There is one additional value the tapDanceAction parameter can ``take: kaleidoscope::TapDance::Tap``. It is called with this argument for each and every tap, even if no action is to be triggered yet. This is so that we can have a way to do some side-effects, like light up LEDs to show progress, and so on.
+
+<h4>Kaleidoscope-TopsyTurvy</h4>
+
+[Kaleidoscope-TopsyTurvy Documentation](https://github.com/keyboardio/Kaleidoscope/blob/master/docs/plugins/TopsyTurvy.md)
+
+TopsyTurvy is a plugin that inverts the behaviour of the Shift key for some selected keys. That is, if configured so, it will input ``!`` when pressing the ``1`` key without ``Shift``, but with the modifier pressed, it will input the original ``1`` symbol.
+