Merge pull request #5 from qmk/master

merge qmk master into yr

.github/workflows/auto_approve.yml

@@ -0,0 +1,18 @@
+name: Automatic Approve
+
+on:
+  schedule:
+    - cron: "*/5 * * * *"
+
+jobs:
+  automatic_approve:
+    runs-on: ubuntu-latest
+
+    if: github.repository == 'qmk/qmk_firmware'
+
+    steps:
+    - uses: mheap/automatic-approve-action@v1
+      with:
+        token: ${{ secrets.QMK_BOT_TOKEN }}
+        workflows: "format.yml,lint.yml,unit_test.yml"
+        dangerous_files: "lib/python/,Makefile,paths.mk,builddefs/"

.gitignore

@@ -93,3 +93,6 @@ user_song_list.h
 compile_commands.json
 .clangd/
 .cache/
+
+# VIA(L) json files that don't belong in QMK repo
+via*.json

data/schemas/definitions.jsonschema

@@ -71,6 +71,22 @@
         "type": "number",
         "min": 0.25
     },
+    "keyboard": {
+        "oneOf": [
+            {
+                "type": "string",
+                "enum": [
+                    "converter/numeric_keypad_IIe",
+                    "emptystring/NQG",
+                    "maple_computing/christmas_tree/V2017"
+                ]
+            },
+            {
+                "type": "string",
+                "pattern": "^[0-9a-z][0-9a-z_/]*$"
+            }
+        ]
+    },
     "mcu_pin_array": {
         "type": "array",
         "items": {"$ref": "#/mcu_pin"}

data/schemas/keyboard.jsonschema

@@ -5,6 +5,7 @@
     "type": "object",
     "properties": {
         "keyboard_name": {"$ref": "qmk.definitions.v1#/text_identifier"},
+        "keyboard_folder": {"$ref": "qmk.definitions.v1#/keyboard"},
         "maintainer": {"$ref": "qmk.definitions.v1#/text_identifier"},
         "manufacturer": {"$ref": "qmk.definitions.v1#/text_identifier"},
         "url": {

docs/feature_led_indicators.md

@@ -11,13 +11,13 @@ QMK provides methods to read 5 of the LEDs defined in the HID spec:
 * Kana
 
 There are three ways to get the lock LED state:
-* by specifying configuration options within `config.h`
-* by implementing `bool led_update_kb(led_t led_state)` or `_user(led_t led_state)`; or
-* by calling `led_t host_keyboard_led_state()`
+* Configuration options in `config.h`
+* Implement `led_update_*` function
+* Call `led_t host_keyboard_led_state()`
 
-!> `host_keyboard_led_state()` may already reflect a new value before `led_update_user()` is called.
+!> The `host_keyboard_led_state()` may reflect an updated state before `led_update_user()` is called.
 
-Two more deprecated functions exist that provide the LED state as a `uint8_t`:
+Two deprecated functions that provide the LED state as `uint8_t`:
 
 * `uint8_t led_set_kb(uint8_t usb_led)` and `_user(uint8_t usb_led)`
 * `uint8_t host_keyboard_leds()`
@@ -37,23 +37,20 @@ To configure the indicators, `#define` these in your `config.h`:
 
 Unless you are designing your own keyboard, you generally should not need to change the above config options.
 
-## `led_update_*()`
+## LED update function
 
-When the configuration options do not provide enough flexibility, the API hooks provided allow custom control of the LED behavior. These functions will be called when the state of one of those 5 LEDs changes. It receives the LED state as a struct parameter.
+When the configuration options do not provide enough flexibility, the following callbacks allow custom control of the LED behavior. These functions will be called when one of those 5 LEDs changes state: 
 
-By convention, return `true` from `led_update_user()` to get the `led_update_kb()` hook to run its code, and
-return `false` when you would prefer not to run the code in `led_update_kb()`.
+* Keyboard/revision: `bool led_update_kb(led_t led_state)`
+* Keymap: `bool led_update_user(led_t led_state)`
 
-Some examples include:
+Both receives LED state as a struct parameter. Returning `true` in `led_update_user()` will allow the keyboard level code in `led_update_kb()` to run as well. Returning `false` will override the keyboard level code, depending on how the keyboard level function is set up.
 
-  - overriding the LEDs to use them for something else like layer indication
-    - return `false` because you do not want the `_kb()` function to run, as it would override your layer behavior.
-  - play a sound when an LED turns on or off.
-    - return `true` because you want the `_kb` function to run, and this is in addition to the default LED behavior.
+?> This boolean return type of `led_update_user` allows for overriding keyboard LED controls, and is thus recommended over the void `led_set_user` function.
 
-?> Because the `led_set_*` functions return `void` instead of `bool`, they do not allow for overriding the keyboard LED control, and thus it's recommended to use `led_update_*` instead.
+### Example of keyboard LED update implementation
 
-### Example `led_update_kb()` Implementation
+This is a template indicator function that can be implemented on keyboard level code:
 
 ```c
 bool led_update_kb(led_t led_state) {
@@ -74,9 +71,9 @@ bool led_update_kb(led_t led_state) {
 }
 ```
 
-### Example `led_update_user()` Implementation
+### Example of user LED update implementation
 
-This incomplete example would play a sound if Caps Lock is turned on or off. It returns `true`, because you also want the LEDs to maintain their state.
+This is an incomplete example will play a sound if Caps Lock is turned on or off. It returns `true` to allow keyboard LED function to maintain their state.
 
 ```c
 #ifdef AUDIO_ENABLE
@@ -96,18 +93,17 @@ bool led_update_user(led_t led_state) {
 }
 ```
 
-### `led_update_*` Function Documentation
-
-* Keyboard/Revision: `bool led_update_kb(led_t led_state)`
-* Keymap: `bool led_update_user(led_t led_state)`
+## Host keyboard LED state 
 
-## `host_keyboard_led_state()`
+The `host_keyboard_led_state()` function will report the LED state returned from the host computer as `led_t`. This is useful for reading the LED state outside `led_update_*`. For example, you can get the boolean state of Caps Lock from the host with:
 
-Call this function to get the last received LED state as a `led_t`. This is useful for reading the LED state outside `led_update_*`, e.g. in [`matrix_scan_user()`](#matrix-scanning-code).
+```c
+bool caps = host_keyboard_led_state().caps_lock;
+```
 
 ## Setting Physical LED State
 
-Some keyboard implementations provide convenience methods for setting the state of the physical LEDs.
+Some keyboard implementations provide convenient methods for setting the state of the physical LEDs.
 
 ### Ergodox Boards
 

docs/i2c_driver.md

@@ -166,7 +166,7 @@ Send multiple bytes to the selected I2C device.
 
 ### `i2c_status_t i2c_receive(uint8_t address, uint8_t* data, uint16_t length, uint16_t timeout)`
 
-Receive multiple bytes from the selected SPI device.
+Receive multiple bytes from the selected I2C device.
 
 #### Arguments
 

docs/zh-cn/newbs_git_best_practices.md

@@ -0,0 +1,23 @@
+# QMK所采用的Git最佳实践
+
+<!---
+  original document: 0.15.17:docs/newbs_git_best_practices.md 
+  git diff 0.15.17 HEAD -- docs/newbs_git_best_practices.md  | cat
+-->
+
+*译者注：对于git相关的部分，除广为接受的名词外，会尽量保留git命令及各种术语的英文版本，部分名词及关键部分会附带中文翻译*
+
+## 或者讲，"怎么才能不害怕并喜欢上Git"
+
+本节旨在以最佳方式指导新手在为QMK做贡献时获得流畅的体验。我们将进行一次完整的QMK贡献操作流程，并在部分环节中详细讲述几种便捷的方法，之后我们会故意搞砸一些东西，并教导你如何回到正轨。
+
+该章节做了如下假设：
+
+1. 你已有Github账号且已[fork了qmk_firmware仓库](zh-cn/getting_started_github.md)到你的账号下。
+2. 已完成了[构建环境](zh-cn/newbs_getting_started.md#set-up-your-environment)及[QMK](zh-cn/newbs_getting_started.md#set-up-qmk)配置。
+
+---
+
+- 第一节：[在你Fork的主干上：频繁更新，不要提交](zh-cn/newbs_git_using_your_master_branch.md)
+- 第二节：[解决合并冲突](zh-cn/newbs_git_resolving_merge_conflicts.md)
+- 第三节：[重新同步一个脱离同步状态的Git分支](zh-cn/newbs_git_resynchronize_a_branch.md)

docs/zh-cn/newbs_git_resolving_merge_conflicts.md

@@ -0,0 +1,86 @@
+# 解决合并冲突
+
+<!---
+  original document: 0.15.17:docs/newbs_git_resolving_merge_conflicts.md 
+  git diff 0.15.17 HEAD -- docs/newbs_git_resolving_merge_conflicts.md  | cat
+-->
+
+有时在你致力于一个较长周期才能完成的分支时，其它人提交的变更会与你提交的pull request中的变更发生冲突。我们将这种多个人编辑同一个模块同一个文件时产生的场景叫做 *合并冲突*
+
+?> 本文中的场景基于[在你Fork的主干上：频繁更新，不要提交](zh-cn/newbs_git_using_your_master_branch.md)一文。如果你对那篇文章不熟悉，请先阅读它，再回来继续。
+
+## 变基/衍合（rebase）
+
+
+Git的*变基*操作会将提交历史中的提交节点摘除并回滚，然后统一提交到一个新节点上。在解决合并冲突时，可以通过对当前分支进行变基，来获取从分支拉取到当前时刻的所有变更。
+
+从执行如下命令开始：
+
+```
+git fetch upstream
+git rev-list --left-right --count HEAD...upstram/master
+```
+
+此处输入的 `git rev-list` 命令可以得到当前分支与QMK主干分支间的提交数量差。而先执行 `git fetch` 是为了确保我们有上游仓库（upstream repo）的最新状态。`git rev-list` 命令会返回两个数字：
+
+```
+$ git rev-list --left-right --count HEAD...upstream/master
+7       35
+```
+
+第一个数字为当前分支自创建后新增的提交数量。第二个数字为当前分支创建后在 `upstream/master` 上的提交数量，而这部分就是我们当前分支上缺失的提交记录。
+
+在我们了解了当前分支以及上游仓库的状态后，可以发起变基操作了：
+
+```
+git rebase upstream/master
+```
+
+这样可以让Git回滚该分支的提交，然后基于QMK的主干版本重新应用这些提交。
+
+*译注：以下内容在中文Git下大同小异，且仅作为示例，不进行翻译*
+```
+$ git rebase upstream/master
+First, rewinding head to replay your work on top of it...
+Applying: Commit #1
+Using index info to reconstruct a base tree...
+M       conflicting_file_1.txt
+Falling back to patching base and 3-way merge...
+Auto-merging conflicting_file_1.txt
+CONFLICT (content): Merge conflict in conflicting_file_1.txt
+error: Failed to merge in the changes.
+hint: Use 'git am --show-current-patch' to see the failed patch
+Patch failed at 0001 Commit #1
+
+Resolve all conflicts manually, mark them as resolved with
+"git add/rm <conflicted_files>", then run "git rebase --continue".
+You can instead skip this commit: run "git rebase --skip".
+To abort and get back to the state before "git rebase", run "git rebase --abort".
+```
+
+以上内容是在告诉我们有合并冲突存在，并给出了冲突所在的文件名。在编辑器中打开该文件，可以在某处发现类似如下形式的内容：
+
+```
+<<<<<<< HEAD
+<p>For help with any issues, email us at [email protected].</p>
+=======
+<p>Need help? Email [email protected].</p>
+>>>>>>> Commit #1
+```
+
+`<<<<<<< HEAD` 标记了合并冲突的起始行，直至 `>>>>>>> Commit #1` 标记的结束行，中间通过 `=======` 分隔开冲突双方。其中 `HEAD` 部分为QMK主干上的版本，标记了提交日志的部分为当前分支的本地提交。
+
+由于Git存储的是*文件差异部分*而非整个文件，所以当Git无法在文件中找到一个变更发生前的内容时，就无法知道如何去进行文件变更，重新编辑一下可以解决问题。在更改完成后，保存文件。
+
+```
+<p>Need help? Email [email protected].</p>
+```
+
+之后，执行：
+
+```
+git add conflicting_file_1.txt
+git rebase --continue
+```
+
+Git即会记录对文件冲突做出的变更，并继续处理剩余的提交，直至全部完成。

docs/zh-cn/newbs_git_resynchronize_a_branch.md

@@ -0,0 +1,76 @@
+# 重新同步已失去同步状态的Git分支
+
+<!---
+  original document: 0.15.17:docs/newbs_git_resynchronize_a_branch.md 
+  git diff 0.15.17 HEAD -- docs/newbs_git_resynchronize_a_branch.md  | cat
+-->
+
+假设你在自己的 `master` 分支之上有提交，并且想和QMK仓库进行同步，可以通过 `git pull` 拉取QMK的 `master` 分支到你的库，但同时Github也会提醒你当前分支相比 `qmk:master` 有几个领先的提交，会在你向QMK发起pr时造成麻烦。
+
+?> 本文中的场景基于[在你Fork的主干上：频繁更新，不要提交](zh-cn/newbs_git_using_your_master_branch.md)一文。如果你对那篇文章不熟悉，请先阅读它，再回来继续。
+
+## 备份你在自己的主干分支上的所有变更（可选）
+
+不会有人想把有用的成果弄丢的。如果你想将你的 `master` 分支上的变更另存一份，简便的方法是直接创建一个当前“脏” `master` 分支的副本：
+
+```
+git branch old_master master
+```
+
+现在 `master` 分支拥有了一个副本分支 `old_master`。
+
+## 重新同步分支
+
+现在可以重新同步 `master` 分支了，这里，我们将QMK仓库设置为Git的远程仓库。通过执行 `git remote -v` 可以确认远程仓库配置，输出信息应类似于：
+
+```
+QMKuser ~/qmk_firmware (master)
+$ git remote -v
+origin  https://github.com/<your_username>/qmk_firmware.git (fetch)
+origin  https://github.com/<your_username>/qmk_firmware.git (push)
+upstream        https://github.com/qmk/qmk_firmware.git (fetch)
+upstream        https://github.com/qmk/qmk_firmware.git (push)
+```
+
+如果你只能看到一个仓库：
+
+```
+QMKuser ~/qmk_firmware (master)
+$ git remote -v
+origin  https://github.com/qmk/qmk_firmware.git (fetch)
+origin  https://github.com/qmk/qmk_firmware.git (push)
+```
+
+通过如下命令添加新的远程仓库：
+
+```
+git remote add upstream https://github.com/qmk/qmk_firmware.git
+```
+
+然后，重新将 `origin` 远程仓库设置为自己的fork：
+
+```
+git remote set-url origin https://github.com/<your_username>/qmk_firmware.git
+```
+
+在两个远程仓库配置完毕后，需要从QMK的 upstream 仓库中获取到更新，执行：
+
+```
+git fetch upstream
+```
+
+此时，重新同步你的分支到QMK的版本：
+
+```
+git reset --hard upstream/master
+```
+
+以上操作会更新你的本地仓库，而你的Github远程仓库仍然处于未同步状态，通过推送，可以让其进入已同步状态。可以通过如下命令来指引Git强行覆盖掉那些仅在你远程仓库中存在的提交：
+
+```
+git push --force-with-lease
+```
+
+!> **不要**在其它使用者也会提交的分支上执行 `git push --force-with-lease`，否则会覆盖掉他人的提交。
+
+此时你的Github fork，本地文件副本，以及QMK仓库就是一致的了。之后再进行变更（[在分支上！](zh-cn/newbs_git_using_your_master_branch.md#making-changes)）和提交。