From 7871a465d36d11c4f9216a9e862104e0e770c6f4 Mon Sep 17 00:00:00 2001 From: ymzcdg <49898694+ymzcdg@users.noreply.github.com> Date: Sun, 12 May 2019 00:22:16 +0800 Subject: [PATCH] translate docs into Mandarin Chinese (#5807) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * translate newbs.md into Madarin Chinese translate newbs.md into Madarin Chinese * translate docs into Mandarin Chinese translate getting_started_github.md into Mandarin Chinese * translate getting_started_getting_help.md into Mandarin Chinese translate getting_started_getting_help.md into Mandarin Chinese * contributing.md to Chinese Personify QMK as a girl named Q酱 . It can make more developer read this document and contribute QMK. * getting_started_introduction.md to Chinese getting_started_introduction.md to Chinese * faq.md to Chinese faq.md to Chinese * crlf2lf getting_started_introduction.md ending line fix getting_started_introduction.md * crlf2lf contributing.md crlf2lf contributing.md --- docs/zh-cn/contributing.md | 205 +++++++++++++++++++++ docs/zh-cn/faq.md | 6 + docs/zh-cn/getting_started_getting_help.md | 15 ++ docs/zh-cn/getting_started_github.md | 59 ++++++ docs/zh-cn/newbs.md | 23 +++ 5 files changed, 308 insertions(+) create mode 100644 docs/zh-cn/contributing.md create mode 100644 docs/zh-cn/faq.md create mode 100644 docs/zh-cn/getting_started_getting_help.md create mode 100644 docs/zh-cn/getting_started_github.md create mode 100644 docs/zh-cn/newbs.md diff --git a/docs/zh-cn/contributing.md b/docs/zh-cn/contributing.md new file mode 100644 index 0000000000..62b956b619 --- /dev/null +++ b/docs/zh-cn/contributing.md @@ -0,0 +1,205 @@ +# 如何做贡献 + +👍🎉 首先感谢各位百忙之中抽空阅读本文档，并为我们无私奉献。给您点赞啦！ 🎉👍 + +第三方的帮助让Q酱成长了许多呢，Q酱也从你们那学到了不少新东西。Q酱希望每一个想帮助我的人都能很方便的做出有用的贡献。在这里我给摩拳擦掌的你们写了一点引导，让你们的代码在不对我做重大改动的情况下都能成功的被采纳哦。 + +* [项目概况](#项目概况) +* [代码规范](#代码规范) +* [一般教程](#一般教程) +* [行为守则对于我来说有何意义?](#行为守则对于我来说有何意义?) + +## 这文章巨长无比不想读啊! 我就想问个问题而已! + +您要是想问关于Q酱的问题的话可以在[OLKB Subreddit](https://reddit.com/r/olkb)或者是[Discord](https://discord.gg/Uq7gcHh)随意问。 + +请记住: + +* 维护Q酱的小可爱有的时候可能会有点忙，不能及时回答您的问题，耐心等等，他们都是很nice的人呀。 +* 维护Q酱的人都是很无私的善良的人。无论是贡献代码还是回答问题，都是义务的。有时见到他们努力回答各种问题，解决各种BUG，Q酱也是很心疼的。 +* 您可以看看下面的教程，可以让您的问题浅显易懂，更容易回答： + * https://opensource.com/life/16/10/how-ask-technical-questions + * http://www.catb.org/esr/faqs/smart-questions.html + +# 项目概况 + +Q酱很大一部分是用C语言组成的，不过有一小部分特性是C++的。怎么说呢，都是我的一部分，两个我都爱。Q酱一般是在键盘上的嵌入式处理器那里工作的，尤其与AVR([LUFA](http://www.fourwalledcubicle.com/LUFA.php))和ARM ([ChibiOS](http://www.chibios.com))两小哥哥搭配，干活不累，嘻嘻。如果您精通Arduino的话您会发现很多熟悉的概念，但也有点不爽，因为您以前的经验可能没法用来帮助Q酱。 + + + +# Q酱，我在哪能帮助你嘞? + +您要是有问题的话可以 [提出一个issue](https://github.com/qmk/qmk_firmware/issues) 或 [在Discord上交流一下](https://discord.gg/Uq7gcHh). + +# Q酱，我如何帮助你? + +您以前是否没为开源贡献过代码，而又想知道帮助Q酱是怎么一回事? 稍安勿躁，咱给您总结一下！ + +0. 先注册一个 [GitHub](https://github.com) 账户。 +1. 做好一个你要贡献的布局，那就要 [找一个你想解决的问题](https://github.com/qmk/qmk_firmware/issues)，或者 [找一个你想添加的特性](https://github.com/qmk/qmk_firmware/issues?q=is%3Aopen+is%3Aissue+label%3Afeature)。 +2. 把关联着问题的仓库分叉（fork）到你的仓库。这样你在`你的GitHub用户名/qmk_firmware`就有一个仓库备份啦。 +3. 使用 `git clone https://github.com/此处添GitHub用户名/此处添仓库名.git`这个命令把仓库同步到你的电脑中。 +4. 您要是想开发一个新特性的话可以先创建一个issue和Q酱的维护者讨论一下您要做什么。 +5. 使用`git checkout -b 此处写分支名字（别用汉字）`命令来创建一个分支（branch）用于开发。 +6. 对要解决的问题或要添加的特性进行适当的更改。 +7. 使用 `git add 把改变的文件的目录写这里` 可以添加改变的文件内容到git用于管理工程状态的索引（快照）里。 +8. 使用 `git commit -m "这里写修改的相关信息"` 来描述你做出了什么修改。 +9. 使用 `git push origin 此处写分支名字`来把你的更改同步到GitHub库里（反正不是打篮球那个库里）。 +10. 提交一个[QMK 固件的pull request](https://github.com/qmk/qmk_firmware/pull/new/master)。 +11. 给你的pull request拟一个标题，包括简短的描述和问题或错误代码。比如, 你可以起一个这样的"Added more log outputting to resolve #4352"（最好用英语，毕竟Q酱的中文也不是那么的溜，有可能会看不懂中文）。 +12. 在描述（description）里面写你做了哪些更改，你的代码里还存在什么问题, 或者你想问维护的小可爱们的问题。你的your pull request有点小问题无伤大雅(本来也没有完美的代码嘛), 维护的小可爱们会竭尽全力帮您改进的！ +13. 维护人员审查代码可能需要一些时间。 +14. 维护人员会通知您要更改什么地方，然后您就按照建议改一改。 +15. 预祝您合并成功！ + +# 代码规范 + +其实也没有什么特别严格的规范啦，但是俗话说的好：没有规矩，不成方圆。您可以看一下您的要改动的代码周围的画风，然后保持队形。如果你感觉周围都不知道是什么牛鬼蛇神的话就看看下面的建议： + +* 我们用肆(4)个空格来缩进(软件中也可以设置到Tab键) +* 我们使用改良的1TBS(允许单行样式) + * 左大括号: 在开放性语句块那行的末尾 + * 右大括号: 和开放性语句块第一个字母对齐 + * Else If: 将右大括号放在行的开头，下一个左大括号放在同一行的结尾 + * 可选大括号: 可选大括号是必选的 + * 应该这样: if (condition) { return false; } + * 不应该这样: if (condition) return false; +* 建议使用C语言风格的注释: `/* */` + * 把注释想象成一个描述特征的故事 + * 充分使用注释来描述你为何这样修改 + * 有些公认的东西就不要写到注释里面了 + * 如果你不知道注释是否多余,看下面 +* 一般不要主动换行，主动换行的话每行不要超过76列 +* 要把 `#pragma once` 放到头文件的开始哦，抛弃老土的(`#ifndef THIS_FILE_H`, `#define THIS_FILE_H`, ..., `#endif`)吧 +* 下面两种预处理命令都可以用: `#ifdef DEFINED` 还有 `#if defined(DEFINED)` + * 以上那句对处女座不是很友好哈，处女座的朋友们就别纠结了，直接 `#if defined(DEFINED)` 。 + * 还有就是选好一种风格就一直用，一直用一直爽，不要朝三暮四, 除非你要变化到多重条件的 `#if`。 + * `#` 和 `if`要挨在一起哦，再让本空格在中间冒充电灯泡本空格会生气的。 + * 以下是缩进规则: + * 首先考虑可读性，强迫症的朋友们总想要保持代码的高一致性，这样可不好。 + * 保证文件已有风格不变。如果代码本来就是杂糅风格，那就见机行事，让你的修改更有意义些。 + * 其实你也可以在缩进的时候看看周围其他代码，然后范水模山，预处理命令可以有自己的缩进风格。 + +可以参照下面: + +```c +/* foo 的 Enums*/ +enum foo_state { + FOO_BAR, + FOO_BAZ, +}; + +/* 有返回值的情况 */ +int foo(void) { + if (some_condition) { + return FOO_BAR; + } else { + return -1; + } +} +``` + +# Clang-format的自动格式化 +[Clang-format](https://clang.llvm.org/docs/ClangFormat.html) 是LLVM的一部分，可以帮你自动格式化代码。我们给你准备好了一个适用于以上规范的配置文件，会帮你调整缩进和换行，你只需要写好括号就好。有了它，你再也不用担心调整代码格式太耗时，没有时间陪伴自己（虚构）的另一半了。 + +使用[LLVM 完整安装](http://llvm.org/builds/)可以在Windows上安装clang-format, Ubuntu用户要用`sudo apt install clang-format`。 + +命令行的朋友们, 加上 `-style=file`选项就会自动在QMK的根目录寻找.clang-format配置文件了。 + +VSCode用户, 标准的 C/C++ 插件就支持clang-format, 或者可以用[独立扩展](https://marketplace.visualstudio.com/items?itemName=LLVMExtensions.ClangFormat)也行。 + +有些东西(比如LAYOUT宏) 会被clang-format打乱，所以那些文件就别用clang-format了,这里就教您一个小窍门，在`// clang-format off` 和 `//clang-format on`之间装上会被搞乱的代码就好了。 + +# 一般教程 + +你可以给Q酱的不同部分添砖加瓦，但也要用不同的方法严谨检查。不论你修改哪里最好还是看看下边。 + +* 将PR（pull request）分成一个个的逻辑单元。 比如，不要一次将两个新特性PR出去。要添加的特性排好队，一个一个来。 +* 提交之前看一眼，`git diff --check`的空格一定要写对了 +* 确定你的代码能通过编译 + * 布局: 确定`make keyboard:your_new_keymap` 不返回错误 + * 键盘: 确定 `make keyboard:all` 不返回错误 + * 核心代码: 确定 `make all` 不返回错误 +* 提交的信息尽量明确。第一行写点简短介绍(每行不多于70个英文字母), 第二行空着,第三行和后面就要写些必要的细节了。最好用英文写，比如: + +``` +Adjust the fronzlebop for the kerpleplork + +The kerpleplork was intermittently failing with error code 23. The root cause was the fronzlebop setting, which causes the kerpleplork to activate every N iterations. + +Limited experimentation on the devices I have available shows that 7 is high enough to avoid confusing the kerpleplork, but I'd like to get some feedback from people with ARM devices to be sure. +``` + +## 文档 + +想帮助Q酱当然是先看文档最简单了。找到这个文档哪里错了然后改正它对于你来说超级简单! 我们也对有写文档能力的人求贤若渴，如果你是对的人[点这个](#Q酱，我在哪能帮助你嘞?)! + +文档呢，都静静的放在`qmk_firmware/docs` 目录里, 也或者您想为网页做贡献的话也是可以的哦。 + +在文档中附代码案例时, 先观察文档其他地方的命名规范。比如, 把enums的名字都改成像`my_layers`或者`my_keycodes`来防止名字不一致的enums被当作特务枪毙: + +```c +enum my_layers { + _FIRST_LAYER, + _SECOND_LAYER +}; + +enum my_keycodes { + FIRST_LAYER = SAFE_RANGE, + SECOND_LAYER +}; +``` + +## 布局 + +大多数QMK新手都从创建一个自己的布局开始。我们尽力保证布局规范宽松 (毕竟布局是个性的体现) 不过建议遵守以下准则，这样可以让别人更好理解你的代码 + +* 用 [模板](documentation_templates.md)写个`readme.md`。 +* 所有的布局PR都会被squash, 如果你想知道你的提交是怎么被squash的那你就自己来吧 +* 不要把新特性和布局一起PR。可以分别PR他们 +* 布局文件夹就不要放`Makefile`了，这个操作都过时啦 +* 更新文件头部的copyrights(看`%YOUR_NAME%`那) + +## 键盘 + +QMK的最终归宿是键盘。有些键盘是社区维护的，有一些是制作这些键盘的人维护的。`readme.md`会告诉你是谁维护了这个键盘，如果你对某个键盘有疑问，可以 [创建一个Issue](https://github.com/qmk/qmk_firmware/issues) 来问一问维护者。 + +我们建议你按下面的来操作: + +* 用[模板](documentation_templates.md)写`readme.md`。 +* 提交数量尽量合理，不然我们可就要把你的PR给squash了。 +* 不要把新特性和新键盘一起PR。可以分别PR他们 +* 用父文件夹的名字命名 `.c`/`.h`文件, 比如`/keyboards///.[ch]` +* 键盘文件夹就不要放`Makefile`了，这个操作都过时啦 +* 更新文件头部的copyrights(看`%YOUR_NAME%`那) + +## Quantum/TMK 核心 + +在您废寝忘食地开发Q酱新特性或者帮Q酱驱虫之前，一定要确保你的工作是有意义的。看看[了解QMK](understanding_qmk.md)你会对Q酱有更深的了解，这个文档将带你领略QMK的程序流程。现在你应该和维护团对谈谈来了解实现你想法的最佳方法了。一下渠道都可以： + +* [在Discord交流](https://discord.gg/Uq7gcHh) +* [建立一个Issue](https://github.com/qmk/qmk_firmware/issues/new) + +新特性和BUG的修复影响所有键盘。开发组也在翻修QMK。所以，在实施重大返修之前一定要讨论一下。如果你在没有事先与维护团队沟通的情况下提交了一个PR，而且你的选择与维护团队的计划方向不符，那你可能要面临大改了。 + +修复BUG或者开发新特性之前看看这个： + +* **默认不启用** - QMK运行的芯片多数内存有限，所以首要考虑的还应该是布局不要被破坏，于是特性默认是不启用的。你喜欢什么特性的话就打开它，如果你觉得有些特性应该默认开启或者你能帮助缩减代码，那就联系维护组吧。 +* **提交之前在本地编译** - 这个简直就是家喻户晓了，但是也确实需要编译啊！ 我们的Travis系统会发现一切问题，但是自己编译一下可要比在线等快多了。 +* **注意版本和芯片平台** - 有那么几个键盘有支持不同配置甚至是不同芯片的版本。试着写一个能AVR和ARM两个平台运行的特性，或者在不支持的平台自动禁用。 +* **解释你的新特性** - 在`docs/`写个文档, 你可以创建新文档或者写到现有文档中。如果你不把它记录下来，其他人就无法从你的努力中获益。 + +也可以看看以下建议： + +* 提交数量尽量合理，不然我们可就要把你的PR给squash了。 +* 不要把新特性、布局和键盘一起PR。可以分别PR他们。 +* 给你的特性写[单元测试](unit_testing.md)。 +* 你编辑的文件风格要一致，如果风格不明确或者是混搭风的，你就要先看看[代码规范](#代码规范)确认情况。 + +## 重构 + +为了保持QMK脉络清晰，Q酱打算深入规划重构一下自己，然后让合作者进行修改。如果你有重构的思路或建议[创建一个issue](https://github.com/qmk/qmk_firmware/issues), Q酱很乐意讨论一下怎么改进一下。 + +# 行为守则对于我来说有何意义? + +我们的[行为守则](https://github.com/qmk/qmk_firmware/blob/master/CODE_OF_CONDUCT.md) 是说明您有责任尊重和礼貌地对待项目中的每个人，无论他们的身份如何。 如果你是我们行为准则所描述的不当行为的受害者，我们将站在你这边，并按照行为准则对施暴者进行适当谴责。 diff --git a/docs/zh-cn/faq.md b/docs/zh-cn/faq.md new file mode 100644 index 0000000000..3d0b65c6fd --- /dev/null +++ b/docs/zh-cn/faq.md @@ -0,0 +1,6 @@ +# 常见问题 + +* [一般问题](faq_general.md) +* [构建和编译QMK](faq_build.md) +* [QMK调试和故障排除](faq_debug.md) +* [布局问题](faq_keymap.md) diff --git a/docs/zh-cn/getting_started_getting_help.md b/docs/zh-cn/getting_started_getting_help.md new file mode 100644 index 0000000000..cf770a7708 --- /dev/null +++ b/docs/zh-cn/getting_started_getting_help.md @@ -0,0 +1,15 @@ +# 获得帮助 + +有很多方法来获得关于QMK的帮助. + +## 实时聊天 + +你可以在我们的主要[Discord服务器](https://discord.gg/Uq7gcHh)找到QMK的开发者和用户。有很多讨论固件的不同频道, 工具箱(Toolbox), 硬件,配置工具(configurator). + +## OLKB Subreddit + +QMK的官方论坛是[/r/olkb](https://reddit.com/r/olkb) 在[reddit.com](https://reddit.com)上. + +## Github的Issue + +你可以在GitHub上 [提出issue](https://github.com/qmk/qmk_firmware/issues).当您的问题需要长期讨论或调试时，这尤其方便。 diff --git a/docs/zh-cn/getting_started_github.md b/docs/zh-cn/getting_started_github.md new file mode 100644 index 0000000000..0400eea643 --- /dev/null +++ b/docs/zh-cn/getting_started_github.md @@ -0,0 +1,59 @@ +# 如何在QMK中使用Github + +Github can be a little tricky to those that aren't familiar with it - this guide will walk through each step of forking, cloning, and submitting a pull request with QMK. + +?> 本教程假设您已安装GitHub，并且您喜欢使用命令行工作。 + +首先 [Github上的QMK页面](https://github.com/qmk/qmk_firmware), 您能看到右上方有个按钮写着"Fork": + +![从Github上分叉](http://i.imgur.com/8Toomz4.jpg) + +如果你是某组织成员，你将需要选择分叉到哪个账户。一般情况下, 你是想要分叉到你的私人账户下。当你完成分叉 (有时需要等一会), 点击"Clone or Download" 按钮: + +!从Github下载](http://i.imgur.com/N1NYcSz.jpg) + +你要选择 "HTTPS", 然后选择链接复制: + +![HTTPS链接](http://i.imgur.com/eGO0ohO.jpg) + +然后，在命令行输入`git clone `，然后粘贴你的链接: + +``` +user@computer:~$ git clone https://github.com/whoeveryouare/qmk_firmware.git +Cloning into 'qmk_firmware'... +remote: Counting objects: 46625, done. +remote: Compressing objects: 100% (2/2), done. +remote: Total 46625 (delta 0), reused 0 (delta 0), pack-reused 46623 +Receiving objects: 100% (46625/46625), 84.47 MiB | 3.14 MiB/s, done. +Resolving deltas: 100% (29362/29362), done. +Checking out files: 100% (2799/2799), done. +``` + +现在你本地计算机有QMK的分叉了,你可以添加你的布局了, 为你的键盘编译并刷新固件吧。如果你觉得你的修改很不错, 你可以添加,提交,然后想你的分叉推出（pull）你的改变，像这样: + +``` +user@computer:~$ git add . +user@computer:~$ git commit -m "adding my keymap" +[master cccb1608] adding my keymap + 1 file changed, 1 insertion(+) + create mode 100644 keyboards/planck/keymaps/mine/keymap.c +user@computer:~$ git push +Counting objects: 1, done. +Delta compression using up to 4 threads. +Compressing objects: 100% (1/1), done. +Writing objects: 100% (1/1), 1.64 KiB | 0 bytes/s, done. +Total 1 (delta 1), reused 0 (delta 0) +remote: Resolving deltas: 100% (1/1), completed with 1 local objects. +To https://github.com/whoeveryouare/qmk_firmware.git + + 20043e64...7da94ac5 master -> master +``` + +现在你的改动已经在你Github上的分支中了 - 如果你回到这 (`https://github.com/你的GitHub账户名/qmk_firmware`) ,你可以点击下方所示按钮创建 "New Pull Request": + +![新的 Pull Request](http://i.imgur.com/DxMHpJ8.jpg) + +现在你可以看到你所做的一切 - 如果看起来不错, 就可以点击 "Create Pull Request"定稿了: + +![创建Pull Request](http://i.imgur.com/Ojydlaj.jpg) + +提交后,我们会开跟你说你的改动,要求您进行更改, 并最终接受您的更改!感谢您为QMK做的贡献 :) diff --git a/docs/zh-cn/newbs.md b/docs/zh-cn/newbs.md new file mode 100644 index 0000000000..8c36b0d24b --- /dev/null +++ b/docs/zh-cn/newbs.md @@ -0,0 +1,23 @@ +# QMK菜鸟教程 + +QMK是为你机械硬盘设计的的一个强大的开源固件。使用QMK可以很简单的让你的定制键盘变得强大。看完这篇文章，无论你是菜鸟还是大佬，都可以顺利的使用QMK来定制键盘。 + +你是否为不知道你的键盘能不能运行QMK而苦恼? 如果你的机械键盘是你自己做的，那么这把键盘一般可以运行QMK。我们提供了[一大堆自制键盘](http://qmk.fm/keyboards/), 所以即便你的键盘不能运行QMK你也很容易能找到满足你需求的键盘。 + +## 概览 + +这个教程有7个主要部分： + +* [新手上路](newbs_getting_started.md) +* [用命令行构建你的第一个固件](newbs_building_firmware.md) +* [用在线界面构建你的第一个固件](newbs_building_firmware_configurator.md) +* [刷新固件](newbs_flashing.md) +* [测试和调试](newbs_testing_debugging.md) +* [Git最佳实践](newbs_best_practices.md) +* [其他学习资源](newbs_learn_more_resources.md) + +这份教程旨在帮助没有固件构建经验的人，也是根据该目的做出选择和建议。这些程序有很多替代方法，大部分替代我们都支持。如果你对完成一个任务有疑问，可以[向我们寻求帮助](getting_started_getting_help.md). + +## 其他资源 + +* [Thomas Baart的 QMK基础博客](https://thomasbaart.nl/category/mechanical-keyboards/firmware/qmk/qmk-basics/) – 这是一个用户创建的博客，涵盖了为新手准备的使用QMK的基础知识。