Merge point for 2019 Aug 30 Breaking Change

10 files changed, 158 insertions, 28 deletions

diff --git a/docs/ChangeLog/20190830.md b/docs/ChangeLog/20190830.md
new file mode 100644
index 000000000..88d7192cb
--- /dev/null
+++ b/docs/ChangeLog/20190830.md
@@ -0,0 +1,47 @@
+# QMK Breaking Change - 2019 Aug 30
+
+Four times a year QMK runs a process for merging Breaking Changes. A Breaking Change is any change which modifies how QMK behaves in a way that is incompatible or potentially dangerous. We limit these changes to 4 times per year so that users can have confidence that updating their QMK tree will not break their keymaps.
+
+This document marks the inaugural Breaking Change merge. A list of changes follows.
+
+## LUFA USB descriptor cleanup
+
+* Some code cleanups related to the USB HID descriptors on AVR keyboards, to make them easier to read and understand
+* More information: see https://github.com/qmk/qmk_firmware/pull/4871
+* No behaviour changes anticipated and no keymaps modified
+
+## Migrating `ACTION_LAYER_MOMENTARY()` entries in `fn_actions` to `MO()` keycodes
+
+* `fn_actions` is deprecated, and its functionality has been superseded by direct keycodes and `process_record_user()`
+* The end result of removing this obsolete feature should result in a decent reduction in firmware size and code complexity
+* All keymaps affected are recommended to switch away from `fn_actions` in favour of the [custom keycode](https://docs.qmk.fm/#/custom_quantum_functions) and [macro](https://docs.qmk.fm/#/feature_macros) features
+
+## Update Atreus to current code conventions
+
+* Duplicate include guards have bypassed the expected header processing behavior
+* All keymaps affected are recommended to remove duplication of `<keyboard>/config.h` to `<keyboard>/keymaps/<user>/config.h` and only provide overrides at the keymap level
+
+## Backport changes to keymap language files from ZSA fork
+
+* Fixes an issue in the `keymap_br_abnt2.h` file that includes the wrong source (`keymap_common.h` instead of `keymap.h`)
+* Updates the `keymap_swedish.h` file to be specific to swedish, and not just "nordic" in general. 
+* Any keymaps using this will need to remove `NO_*` and replace it with `SE_*`. 
+
+## Update repo to use LUFA as a git submodule
+
+* `/lib/LUFA` removed from the repo
+* LUFA set as a submodule, pointing to qmk/lufa
+* This should allow more flexibility with LUFA, and allow us to keep the sub-module up to date, a lot more easily.  It was ~2 years out of date with no easy path to fix that.  This prevents that from being an issue in the future
+  
+## Migrating `ACTION_BACKLIGHT_*()` entries in `fn_actions` to `BL_` keycodes
+
+* `fn_actions` is deprecated, and its functionality has been superseded by direct keycodes and `process_record_user()`
+* All keymaps using these actions have had the relevant `KC_FN*` keys replaced with the equivalent `BL_*` keys
+* If you currently use `KC_FN*` you will need to replace `fn_actions` with the [custom keycode](https://docs.qmk.fm/#/custom_quantum_functions) and [macro](https://docs.qmk.fm/#/feature_macros) features
+
+## Remove `KC_DELT` alias in favor of `KC_DEL`
+
+* `KC_DELT` was a redundant, undocumented alias for `KC_DELETE`
+* It has been removed and all its uses replaced with the more common `KC_DEL` alias
+* Around 90 keymaps (mostly for ErgoDox boards) have been modified as a result
+
diff --git a/docs/ChangeLog/20190830/PR4871.md b/docs/ChangeLog/20190830/PR4871.md
deleted file mode 100644
index e4ea171d7..000000000
--- a/docs/ChangeLog/20190830/PR4871.md
+++ /dev/null
@@ -1,4 +0,0 @@
-* LUFA USB descriptor cleanup
-    * Some code cleanups related to the USB HID descriptors on AVR keyboards, to make them easier to read and understand
-    * More information: see https://github.com/qmk/qmk_firmware/pull/4871
-    * No behaviour changes anticipated and no keymaps modified
diff --git a/docs/ChangeLog/20190830/PR5176.md b/docs/ChangeLog/20190830/PR5176.md
deleted file mode 100644
index c01b2cb1e..000000000
--- a/docs/ChangeLog/20190830/PR5176.md
+++ /dev/null
@@ -1,4 +0,0 @@
-* Migrating `ACTION_LAYER_MOMENTARY()` entries in `fn_actions` to `MO()` keycodes
-    * `fn_actions` is deprecated, and its functionality has been superseded by direct keycodes and `process_record_user()`
-    * The end result of removing this obsolete feature should result in a decent reduction in firmware size and code complexity
-    * All keymaps affected are recommended to switch away from `fn_actions` in favour of the [custom keycode](https://docs.qmk.fm/#/custom_quantum_functions) and [macro](https://docs.qmk.fm/#/feature_macros) features
diff --git a/docs/ChangeLog/20190830/PR5849.md b/docs/ChangeLog/20190830/PR5849.md
deleted file mode 100644
index 24dadc1f2..000000000
--- a/docs/ChangeLog/20190830/PR5849.md
+++ /dev/null
@@ -1,3 +0,0 @@
-*  Update Atreus to current code conventions
-    * Duplicate include guards have bypassed the expected header processing behavior
-    * All keymaps affected are recommended to remove duplication of `<keyboard>/config.h` to `<keyboard>/keymaps/<user>/config.h` and only provide overrides at the keymap level
\ No newline at end of file
diff --git a/docs/ChangeLog/20190830/PR6198.md b/docs/ChangeLog/20190830/PR6198.md
deleted file mode 100644
index 9141ac250..000000000
--- a/docs/ChangeLog/20190830/PR6198.md
+++ /dev/null
@@ -1,4 +0,0 @@
-* Backport changes to keymap language files from ZSA fork
-  * Fixes an issue in the `keymap_br_abnt2.h` file that includes the wrong source (`keymap_common.h` instead of `keymap.h`)
-  * Updates the `keymap_swedish.h` file to be specific to swedish, and not just "nordic" in general. 
-  * Any keymaps using this will need to remove `NO_*` and replace it with `SE_*`. 
diff --git a/docs/ChangeLog/20190830/PR6245.md b/docs/ChangeLog/20190830/PR6245.md
deleted file mode 100644
index 62e71eee9..000000000
--- a/docs/ChangeLog/20190830/PR6245.md
+++ /dev/null
@@ -1,5 +0,0 @@
-* Update repo to use LUFA as a git submodule
-  * `/lib/LUFA` removed from the repo
-  * LUFA set as a submodule, pointing to qmk/lufa
-  * This should allow more flexibility with LUFA, and allow us to keep the sub-module up to date, a lot more easily.  It was ~2 years out of date with no easy path to fix that.  This prevents that from being an issue in the future
-  
diff --git a/docs/ChangeLog/20190830/PR6299.md b/docs/ChangeLog/20190830/PR6299.md
deleted file mode 100644
index 43fb9e031..000000000
--- a/docs/ChangeLog/20190830/PR6299.md
+++ /dev/null
@@ -1,4 +0,0 @@
-* Migrating `ACTION_BACKLIGHT_*()` entries in `fn_actions` to `BL_` keycodes
-    * `fn_actions` is deprecated, and its functionality has been superseded by direct keycodes and `process_record_user()`
-    * All keymaps using these actions have had the relevant `KC_FN*` keys replaced with the equivalent `BL_*` keys
-    * If you currently use `KC_FN*` you will need to replace `fn_actions` with the [custom keycode](https://docs.qmk.fm/#/custom_quantum_functions) and [macro](https://docs.qmk.fm/#/feature_macros) features
diff --git a/docs/ChangeLog/20190830/PR6327.md b/docs/ChangeLog/20190830/PR6327.md
deleted file mode 100644
index 233e10e09..000000000
--- a/docs/ChangeLog/20190830/PR6327.md
+++ /dev/null
@@ -1,4 +0,0 @@
-* Remove `KC_DELT` alias in favor of `KC_DEL`
-    * `KC_DELT` was a redundant, undocumented alias for `KC_DELETE`
-    * It has been removed and all its uses replaced with the more common `KC_DEL` alias
-    * Around 90 keymaps (mostly for ErgoDox boards) have been modified as a result
diff --git a/docs/_summary.md b/docs/_summary.md
index 95286ff46..d7a49a968 100644
--- a/docs/_summary.md
+++ b/docs/_summary.md
@@ -13,6 +13,9 @@
   * [How to Use Github](getting_started_github.md)
   * [Getting Help](getting_started_getting_help.md)
 
+* [Breaking Changes](breaking_changes.md)
+  * [2019 Aug 30](ChangeLog/20190830.md)
+
 * [FAQ](faq.md)
   * [General FAQ](faq_general.md)
   * [Build/Compile QMK](faq_build.md)
diff --git a/docs/breaking_changes.md b/docs/breaking_changes.md
new file mode 100644
index 000000000..b193b12da
--- /dev/null
+++ b/docs/breaking_changes.md
@@ -0,0 +1,108 @@
+# Breaking Changes
+
+This document describes QMK's Breaking Change process. A Breaking Change is any change which modifies how QMK behaves in a way that in incompatible or potentially dangerous. We limit these changes so that users can have confidence that updating their QMK tree will not break their keymaps.
+
+The breaking change period is when we will merge PR's that change QMK in dangerous or unexpected ways. There is a built-in period of testing so we are confident that any problems caused are rare or unable to be predicted.
+
+## What has been included in past Breaking Changes?
+
+* [2019 Aug 30](ChangeLog/20190830.md)
+
+## When is the next Breaking Change?
+
+The next Breaking Change is scheduled for Nov 29.
+
+### Important Dates
+
+* [ ] 2019 Oct 04 - `future` is created. It will be rebased weekly.
+* [ ] 2019 Nov 01 - `future` closed to new PR's.
+* [ ] 2019 Nov 01 - Call for testers.
+* [ ] 2019 Nov 27 - `master` is locked, no PR's merged.
+* [ ] 2019 Nov 29 - Merge `future` to `master`.
+* [ ] 2019 Nov 30 - `master` is unlocked. PR's can be merged again.
+
+## What changes will be included?
+
+To see a list of breaking change candidates you can look at the [`breaking_change` label](https://github.com/qmk/qmk_firmware/pulls?q=is%3Aopen+label%3Abreaking_change+is%3Apr). New changes might be added between now and when `future` is closed, and a PR with that label applied is not guaranteed to be merged.
+
+If you want your breaking change to be included in this round you need to create a PR with the `breaking_change` label and have it accepted before `future` closes. After `future` closes no new breaking changes will be accepted.
+
+Criteria for acceptance:
+
+* PR is complete and ready to merge
+* PR has a ChangeLog
+
+# Checklists
+
+This section documents various processes we use when running the Breaking Changes process.
+
+## Rebase `future` from `master`
+
+This is run every Friday while `future` is open.
+
+Process:
+
+```
+cd qmk_firmware
+git checkout master
+git pull --ff-only
+git checkout future
+git rebase master
+git push --force
+```
+
+## 8 Weeks Before Merge
+
+* `qmk_firmware` git commands
+    * [ ] `git checkout master`
+    * [ ] `git pull --ff-only`
+    * [ ] `git checkout -b future`
+    * [ ] Edit `readme.md`
+        * [ ] Add a big notice at the top that this is a testing branch.
+        * [ ] Include a link to this document
+    * [ ] `git commit -m 'Branch point for <DATE> Breaking Change'`
+    * [ ] `git tag breakpoint_<YYYY>_<MM>_<DD>`
+    * [ ] `git tag <next_version>` # Prevent the breakpoint tag from confusing version incrementing
+    * [ ] `git push origin future`
+    * [ ] `git push --tags`
+* GitHub Actions
+    * [ ] Switch all [breaking_change PR's](https://github.com/qmk/qmk_firmware/pulls?utf8=%E2%9C%93&q=is%3Apr+is%3Aopen+label%3Abreaking_change) to `future`
+    * [ ] Any that have a ChangeLog entry may be merged immediately.
+
+## 4 Weeks Before Merge
+
+* `future` is now closed to new PR's, only fixes for current PR's may be merged
+* Post call for testers
+    * [ ] Discord
+    * [ ] GitHub PR
+    * [ ] https://reddit.com/r/olkb
+
+## 1 Week Before Merge
+
+* Announce that master will be closed from <2 Days Before> to <Day of Merge>
+    * [ ] Discord
+    * [ ] GitHub PR
+    * [ ] https://reddit.com/r/olkb
+
+## 2 Days Before Merge
+
+* Announce that master is closed for 2 days
+    * [ ] Discord
+    * [ ] GitHub PR
+    * [ ] https://reddit.com/r/olkb
+
+## Day Of Merge
+
+* `qmk_firmware` git commands
+    * [ ] `git checkout future`
+    * [ ] `git pull --ff-only`
+    * [ ] `git rebase origin/master`
+    * [ ] Edit `readme.md`
+        * [ ] Remove the notes about `future`
+    * [ ] Roll up the ChangeLog into one file.
+    * [ ] `git commit -m 'Merge point for <DATE> Breaking Change'`
+    * [ ] `git push origin future`
+* Github Actions
+    * [ ] Create a PR for `future`
+    * [ ] Make sure travis comes back clean
+    * [ ] Merge `future` PR