Update UPGRADING.md too

Rearranged a little, so deprecation is a section, and we can put other things,
notes, into the document. With the rearrangement, added a section about the new
plugin API, and explained the API version bump too.

Signed-off-by: Gergely Nagy <algernon@keyboard.io>

UPGRADING.md

@@ -1,5 +1,33 @@
+Kaleidoscope upgrade notes
+==========================
+
+Noteworthy features
+-------------------
+
+### New plugin API
+
+A new plugin API was introduced in May 2018, which replaces the old system
+(which still continues to work, but see below). The new system is hopefully
+easier to use and develop for:
+
+ - It does not require one to register / use hooks anymore. Implementing the
+   interface provided by `kaleidoscope::Plugin` is all that is required.
+ - The new system has more hook points, and the method names are much more clear
+   now.
+
+### KALEIDOSCOPE_API_VERSION bump
+
+`KALEIDOSCOPE_API_VERSION` has been bumped to **2** due to the plugin API
+changes. It does not mean that version two of the API is final, though. The bump
+is there so plugins can check it, and make compile-time decisions based on it.
+Such as whether to compile for the version one, or for the version two API.
+
+The API version will remain the same, even if we introduce breaking changes -
+until a stable release is made from the v2 branch. From that point onwards, the
+API version will change with further breaking changes.
+
 Deprecated APIs and their replacements
-======================================
+--------------------------------------
 
 As the firmware evolves, there are - and will be - APIs that we deprecate, and
 eventually remove. This document is a short guide that lists the deprecations -
@@ -10,12 +38,12 @@ If any of this does not make sense to you, or you have trouble updating your
 .ino sketch, do not hesitate to write us at help@keyboard.io, we can help you
 fix it.
 
-## Sheduled for removal by 2018-05-26
+### Sheduled for removal by 2018-05-26
 
 These APIs and functions have been deprecated for a long time, and as far as we
 can tell, aren't used by any third party or user code anymore.
 
-### Kaleidoscope.setup(KEYMAP_SIZE)
+#### Kaleidoscope.setup(KEYMAP_SIZE)
 
 The `Kaleidoscope.setup()` method is still around, and is **not** deprecated,
 but the variant of it that takes a keymap size is, and has been since October
@@ -24,7 +52,7 @@ but the variant of it that takes a keymap size is, and has been since October
 Instead, one should use the argument-less `Kaleidoscope.setup()`, and the new
 `KEYMAP()` macros to define a keymap.
 
-### event_handler_hook_use, loop_hook_use, and USE_PLUGINS
+#### event_handler_hook_use, loop_hook_use, and USE_PLUGINS
 
 Deprecated in October 2017, these are old aliases that should no longer be in
 use. They were replaced by `Kaleidoscope.useEventHandlerHook`,
@@ -33,19 +61,19 @@ use. They were replaced by `Kaleidoscope.useEventHandlerHook`,
 The replacements themselves are also deprecated - see below -, but their removal
 will come at a later date.
 
-### MOMENTARY_OFFSET
+#### MOMENTARY_OFFSET
 
 Deprecated in October 2017, replaced by `LAYER_SHIFT_OFFSET`.
 
 This symbol was meant to be used by plugins, not user code, and as far as we
 know, no third party plugin ever used it.
 
-### key_was_pressed, key_is_pressed, key_toggled_on, key_toggled_off
+#### key_was_pressed, key_is_pressed, key_toggled_on, key_toggled_off
 
 Deprecated in July 2017, replaced by `keyWasPressed`, `keyIsPressed`,
 `keyToggledOn`, and `keyToggledOff`, respectively.
 
-## Sheduled for removal by 2018-07-12
+### Sheduled for removal by 2018-07-12
 
 We aim at making a new release by mid-July, and APIs we deprecate now, will be
 removed shortly before the major release. We may deprecate further APIs during
@@ -53,7 +81,7 @@ the next month (until mid-June), and those deprecations will share the same
 removal date. We will try our best to minimize deprecations, and do them as soon
 as possible, to give everyone at least a month to prepare and update.
 
-### Kaleidoscope.use()
+#### Kaleidoscope.use()
 
 Deprecated in May 2018, this method is part of the old plugin API, replaced by
 `KALEIDOSCOPE_INIT_PLUGINS`. To upgrade, you need to modify your .ino sketch
@@ -80,7 +108,7 @@ void setup() {
 }
 ```
 
-### The old-style (v1) plugin API
+#### The old-style (v1) plugin API
 
 This includes using `KaleidoscopePlugin`, `Kaleidoscope.useEventHandlerHook`,
 `Kaleidoscope.replaceEventHandlerHook`, `Kaleidoscope.appendEventHandlerHook`,