Minor cleanup to breaking/checklist docs. (#19596)

Co-authored-by: Ryan <fauxpark@gmail.com>

4 files changed, 48 insertions, 22 deletions

diff --git a/docs/ChangeLog/20190830.md b/docs/ChangeLog/20190830.md
index ab6e28c4d9..298ec958c5 100644
--- a/docs/ChangeLog/20190830.md
+++ b/docs/ChangeLog/20190830.md
@@ -7,7 +7,7 @@ This document marks the inaugural Breaking Change merge. A list of changes follo
 ## Core code formatting with clang-format
 
 * All core files (`drivers/`, `quantum/`, `tests/`, and `tmk_core/`) have been formatted with clang-format
-* A travis process to reformat PR's on merge has been instituted
+* A travis process to reformat PRs on merge has been instituted
 * You can use the new CLI command `qmk cformat` to format before submitting your PR if you wish.
 
 ## LUFA USB descriptor cleanup
@@ -30,15 +30,15 @@ This document marks the inaugural Breaking Change merge. A list of changes follo
 ## 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_*`. 
+* 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()`
diff --git a/docs/breaking_changes.md b/docs/breaking_changes.md
index 586e998a1c..a3f05cbfac 100644
--- a/docs/breaking_changes.md
+++ b/docs/breaking_changes.md
@@ -4,7 +4,9 @@ This document describes QMK's Breaking Change process. A Breaking Change is any
 
 This also includes any keyboard moves within the repository.
 
-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.
+The breaking change period is when we will merge PRs 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.
+
+Practically, this means QMK merges the `develop` branch into the `master` branch on a 3-month cadence.
 
 ## What has been included in past Breaking Changes?
 
@@ -29,25 +31,34 @@ The next Breaking Change is scheduled for February 26, 2023.
 ### Important Dates
 
 * 2022 Nov 26 - `develop` is tagged with a new release version. Each push to `master` is subsequently merged to `develop` by GitHub actions.
-* 2023 Jan 29 - `develop` closed to new PR's.
+* 2023 Jan 29 - `develop` closed to new PRs.
 * 2023 Jan 29 - Call for testers.
 * 2023 Feb 12 - Last day for merges -- after this point `develop` is locked for testing and accepts only bugfixes
-* 2023 Feb 19 - `develop` is locked, only critical bugfix PR's merged.
-* 2023 Feb 24 - `master` is locked, no PR's merged.
+* 2023 Feb 19 - `develop` is locked, only critical bugfix PRs merged.
+* 2023 Feb 24 - `master` is locked, no PRs merged.
 * 2023 Feb 26 - Merge `develop` to `master`.
-* 2023 Feb 26 - `master` is unlocked. PR's can be merged again.
+* 2023 Feb 26 - `master` is unlocked. PRs 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 `develop` is closed, and a PR with that label applied is not guaranteed to be merged.
+To see a list of breaking changes merge candidates you can look at the [`core` label](https://github.com/qmk/qmk_firmware/pulls?q=is%3Aopen+label%3Acore+is%3Apr). This label is applied whenever a PR is raised or changed, but only if the PR includes changes to core areas of QMK Firmware. A PR with that label applied is not guaranteed to be merged in the current cycle. New changes might be added between now and when `develop` is closed, and it is generally the responsibility of the submitter to handle conflicts. There is also another label used by QMK Collaborators -- `breaking_change_YYYYqN` -- which signifies to maintainers that it is a strong candidate for inclusion, and should be prioritised for review.
+
+If you want your breaking change to be included in this round you need to create a PR and have it accepted by QMK Collaborators before `develop` closes. After `develop` closes, new submissions will be deferred to the next breaking changes cycle.
 
-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 `develop` closes. After `develop` closes no new breaking changes will be accepted.
+The simpler your PR is, the easier it is for maintainers to review, thus a higher likelihood of a faster merge. Large PRs tend to require a lot of attention, refactoring, and back-and-forth with subsequent reviews -- with other PRs getting merged in the meantime larger unmerged PRs are far more likely to be susceptible to conflicts.
 
 Criteria for acceptance:
 
 * The PR is complete and ready to merge
+* GitHub checks for the PR are green whenever possible
+    * A "red" check may be disregarded by maintainers if the items flagged are unrelated to the change proposed in the PR
+        * Modifications to existing files should not need to add license headers to pass lint, for instance.
+        * If it's not directly related to your PR's functionality, prefer avoiding making a change.
+
+Strongly suggested:
+
 * The PR has a ChangeLog file describing the changes under `<qmk_firmware>/docs/Changelog/20221126`.
-    * This should be in Markdown format, with a name in the format `PR12345.md`, substituting the digits for your PR's ID.
+    * This should be in Markdown format, with a name in the format `PR12345.md`, substituting the digits for your PRs ID.
     * One strong recommendation that the ChangeLog document matches the PR description on GitHub, so as to ensure traceability.
 
 ## Checklists
@@ -56,7 +67,7 @@ This section documents various processes we use when running the Breaking Change
 
 ### 4 Weeks Before Merge
 
-* `develop` is now closed to new PR's, only fixes for current PR's may be merged
+* `develop` is now closed to new PRs, only fixes for current PRs may be merged
 * Post call for testers: message `@Breaking Changes Updates` on `#qmk_firmware` in Discord:
     * `@Breaking Changes Updates -- Hey folks, last day for functional PRs to be raised against qmk_firmware for this breaking changes cycle is today.`
 
diff --git a/docs/contributing.md b/docs/contributing.md
index 91833e30df..bb46add789 100644
--- a/docs/contributing.md
+++ b/docs/contributing.md
@@ -118,8 +118,8 @@ and navigating to `http://localhost:8936/`.
 Most first-time QMK contributors start with their personal keymaps. We try to keep keymap standards pretty casual (keymaps, after all, reflect the personality of their creators) but we do ask that you follow these guidelines to make it easier for others to discover and learn from your keymap.
 
 * Write a `readme.md` using [the template](documentation_templates.md).
-* All Keymap PR's are squashed, so if you care about how your commits are squashed you should do it yourself
-* Do not lump features in with keymap PR's. Submit the feature first and then a second PR for the keymap.
+* All Keymap PRs are squashed, so if you care about how your commits are squashed you should do it yourself
+* Do not lump features in with keymap PRs. Submit the feature first and then a second PR for the keymap.
 * Do not include `Makefile`s in your keymap folder (they're no longer used)
 * Update copyrights in file headers (look for `%YOUR_NAME%`)
 
@@ -143,7 +143,7 @@ Before you put a lot of work into building your new feature you should make sure
 * [Chat on Discord](https://discord.gg/Uq7gcHh)
 * [Open an Issue](https://github.com/qmk/qmk_firmware/issues/new)
 
-Feature and Bug Fix PR's affect all keyboards. We are also in the process of restructuring QMK. For this reason it is especially important for significant changes to be discussed before implementation has happened. If you open a PR without talking to us first please be prepared to do some significant rework if your choices do not mesh well with our planned direction.
+Feature and Bug Fix PRs affect all keyboards. We are also in the process of restructuring QMK. For this reason it is especially important for significant changes to be discussed before implementation has happened. If you open a PR without talking to us first please be prepared to do some significant rework if your choices do not mesh well with our planned direction.
 
 Here are some things to keep in mind when working on your feature or bug fix.
 
diff --git a/docs/pr_checklist.md b/docs/pr_checklist.md
index 922cb19d9c..683685bda8 100644
--- a/docs/pr_checklist.md
+++ b/docs/pr_checklist.md
@@ -9,15 +9,20 @@ If there are any inconsistencies with these recommendations, you're best off [cr
 - PR should be submitted using a non-`master` branch on the source repository
     - this does not mean you target a different branch for your PR, rather that you're not working out of your own master branch
     - if submitter _does_ use their own `master` branch, they'll be given a link to the ["how to git"](newbs_git_using_your_master_branch.md) page after merging -- (end of this document will contain the contents of the message)
+- PRs should contain the smallest amount of modifications required for a single change to the codebase
+    - multiple keyboards at the same time is not acceptable
+        - exception: keymaps for a single user targeting multiple keyboards and/or userspace is acceptable
+    - **the smaller the PR, the higher likelihood of a quicker review, higher likelihood of quicker merge, and less chance of conflicts**
 - newly-added directories and filenames must be lowercase
-    - this rule may be relaxed if upstream sources originally had uppercase characters (e.g. LUFA, ChibiOS, or imported files from other repositories etc.)
+    - the lowercase requirement may be relaxed if upstream sources originally had uppercase characters (e.g. LUFA, ChibiOS, or imported files from other repositories etc.)
     - if there is valid justification (i.e. consistency with existing core files etc.) this can be relaxed
         - a board designer naming their keyboard with uppercase letters is not enough justification
 - valid license headers on all `*.c` and `*.h` source files
     - GPL2/GPL3 recommended for consistency
-    - an example GPL2+ license header may be copied and modified from the bottom of this document
-    - other licenses are permitted, however they must be GPL-compatible and must allow for redistribution. Using a different license will almost certainly delay a PR getting merged.
+    - an example GPL2+ license header may be copied (and author modified) from the bottom of this document
+    - other licenses are permitted, however they must be GPL-compatible and must allow for redistribution. Using a different license will almost certainly delay a PR getting merged
     - missing license headers will prevent PR merge due to ambiguity with license compatibility
+        - simple assignment-only `rules.mk` files should not need a license header - where additional logic is used in an `*.mk` file a license header may be appropriate
 - QMK Codebase "best practices" followed
     - this is not an exhaustive list, and will likely get amended as time goes by
     - `#pragma once` instead of `#ifndef` include guards in header files
@@ -31,13 +36,14 @@ If there are any inconsistencies with these recommendations, you're best off [cr
         - refactor it as a separate core change
         - remove your specific copy in your board
 - fix all merge conflicts before opening the PR (in case you need help or advice, reach out to QMK Collaborators on Discord)
+    - PR submitters will need to keep up-to-date with their base branch, resolving conflicts along the way
 
 ## Keymap PRs
 
 - `#include QMK_KEYBOARD_H` preferred to including specific board files
 - prefer layer `enum`s to `#define`s
 - require custom keycode `enum`s to `#define`s, first entry must have ` = SAFE_RANGE`
-- terminating backslash (`\`) in lines of LAYOUT macro parameters is superfluous
+- terminating backslash (`\`) in lines of LAYOUT macro parameters is superfluous and should be removed
 - some care with spacing (e.g., alignment on commas or first char of keycodes) makes for a much nicer-looking keymap
 
 ## Keyboard PRs
@@ -45,6 +51,9 @@ If there are any inconsistencies with these recommendations, you're best off [cr
 Closed PRs (for inspiration, previous sets of review comments will help you eliminate ping-pong of your own reviews):
 https://github.com/qmk/qmk_firmware/pulls?q=is%3Apr+is%3Aclosed+label%3Akeyboard
 
+- keyboard moves within the repository *must* go through the `develop` branch instead of `master`, so as to ensure compatibility for users
+    - `data/mappings/keyboard_aliases.hjson` must be updated to reflect the move, so users with pre-created configurator keymap.json files continue to detect the correct keyboard
+- PR submissions from a `kbfirmware` export (or equivalent) will not be accepted unless converted to new QMK standards -- try `qmk import-kbfirmware` first
 - `info.json`
     - With the move to [data driven](https://docs.qmk.fm/#/data_driven_config) keyboard configuration, we encourage contributors to utilise as many features as possible of the info.json [schema](https://github.com/qmk/qmk_firmware/blob/master/data/schemas/keyboard.jsonschema).
     - the mandatory elements for a minimally complete `info.json` at present are:
@@ -55,8 +64,11 @@ https://github.com/qmk/qmk_firmware/pulls?q=is%3Apr+is%3Aclosed+label%3Akeyboard
         - `layout` definitions should include matrix positions, so that `LAYOUT` macros can be generated at build time
             - should use standard definitions if applicable
             - use the Community Layout macro names where they apply (preferred above `LAYOUT`/`LAYOUT_all`)
-            - use of `LAYOUT_all` is only valid when providing additional layout macros
-              - providing only `LAYOUT_all` is invalid - especially when implementing the additional layouts within 3rd party tooling
+            - If the keyboard only has a single electrical/switch layout:
+                - use `LAYOUT` as your macro name, unless a community layout already exists
+            - If the keyboard has multiple electrical/switch layouts:
+                - include a `LAYOUT_all` which specifies all possible layout positions in the electrical matrix
+                - use alternate layout names for all other possible layouts, preferring community layout names if an equivalent is available (e.g. `LAYOUT_tkl_ansi`, `LAYOUT_ortho_4x4` etc.)
 - `readme.md`
     - standard template should be present -- [link to template](https://github.com/qmk/qmk_firmware/blob/master/data/templates/keyboard/readme.md)
     - flash command is present, and has `:flash` at end
@@ -139,6 +151,9 @@ Also, specific to ChibiOS:
     - for new hardware support such as display panels, core-side matrix implementations, or other peripherals, an associated keymap should be provided
     - if an existing keymap exists that can leverage this functionality this may not be required (e.g. a new RGB driver chip, supported by the `rgb` keymap) -- consult with the QMK Collaborators on Discord to determine if there is sufficient overlap already
 - any features adding `_kb`/`_user` callbacks must return a `bool`, to allow for user override of keyboard-level callbacks.
+- where relevant, unit tests are strongly recommended -- they boost the confidence level that changes behave correctly
+    - critical areas of the code -- such as the keycode handling pipeline -- will almost certainly require unit tests accompanying them to ensure current and future correctness
+    - you should not be surprised if a QMK collaborator requests unit tests to be included in your PR if it's critical functionality
 - other requirements are at the discretion of QMK collaborators
     - core is a lot more subjective given the breadth of posted changes