2020-11-10 15:02:44 +00:00
# 如何做贡献
👍🎉 首先感谢各位百忙之中抽空阅读本文档，并为我们无私奉献。给您点赞啦！ 🎉👍
第三方的帮助让Q酱成长了许多呢， ，
* [项目概况 ](#项目概况 )
* [代码规范 ](#代码规范 )
* [一般教程 ](#一般教程 )
* [行为守则对于我来说有何意义? ](#行为守则对于我来说有何意义? )
## 这文章巨长无比不想读啊! 我就想问个问题而已!
您要是想问关于Q酱的问题的话可以在[OLKB Subreddit](https://reddit.com/r/olkb)或者是[Discord](https://discord.gg/Uq7gcHh)随意问。
请记住:
* 维护Q酱的小可爱有的时候可能会有点忙， ， ，
* 维护Q酱的人都是很无私的善良的人。无论是贡献代码还是回答问题， ， ，
* 您可以看看下面的教程，可以让您的问题浅显易懂，更容易回答：
* https://opensource.com/life/16/10/how-ask-technical-questions
* http://www.catb.org/esr/faqs/smart-questions.html
# 项目概况
2021-01-30 11:02:49 +00:00
Q酱很大一部分是用C语言组成的， ， ， ， ， ， ， ，
2020-11-10 15:02:44 +00:00
<!-- 需要修正: 这里放些学习C语言的资源。另外感谢修正的小可爱。谢谢您了。 -->
# Q酱，
您要是有问题的话可以 [提出一个issue ](https://github.com/qmk/qmk_firmware/issues ) 或 [在Discord上交流一下 ](https://discord.gg/Uq7gcHh ).
# 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. 把关联着问题的仓库分叉（ ）
3. 使用 `git clone https://github.com/此处添GitHub用户名/此处添仓库名.git` 这个命令把仓库同步到你的电脑中。
4. 您要是想开发一个新特性的话可以先创建一个issue和Q酱的维护者讨论一下您要做什么。
5. 使用`git checkout -b 此处写分支名字（别用汉字）`命令来创建一个分支（ ）
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拟一个标题， #4352 "（ ， ， ）
12. 在描述（ ） ，
13. 维护人员审查代码可能需要一些时间。
14. 维护人员会通知您要更改什么地方，然后您就按照建议改一改。
15. 预祝您合并成功！
# 代码规范
其实也没有什么特别严格的规范啦，但是俗话说的好：没有规矩，不成方圆。您可以看一下您的要改动的代码周围的画风，然后保持队形。如果你感觉周围都不知道是什么牛鬼蛇神的话就看看下面的建议：
* 我们用肆(4)个空格来缩进(软件中也可以设置到Tab键)
* 我们使用改良的1TBS(允许单行样式)
* 左大括号: 在开放性语句块那行的末尾
* 右大括号: 和开放性语句块第一个字母对齐
* Else If: 将右大括号放在行的开头，下一个左大括号放在同一行的结尾
* 可选大括号: 可选大括号是必选的
* 应该这样: if (condition) { return false; }
* 不应该这样: if (condition) return false;
* 建议使用C语言风格的注释: `/* */`
* 把注释想象成一个描述特征的故事
* 充分使用注释来描述你为何这样修改
* 有些公认的东西就不要写到注释里面了
* 如果你不知道注释是否多余,看下面
* 一般不要主动换行，
* 要把 `#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的一部分， ， ， ， ， （ ）
2021-01-30 11:02:49 +00:00
使用[LLVM 完整安装](https://llvm.org/builds/)可以在Windows上安装clang-format, Ubuntu用户要用`sudo apt install clang-format`。
2020-11-10 15:02:44 +00:00
命令行的朋友们, 加上 `-style=file` 选项就会自动在QMK的根目录寻找.clang-format配置文件了。
VSCode用户, 标准的 C/C++ 插件就支持clang-format, 或者可以用[独立扩展](https://marketplace.visualstudio.com/items?itemName=LLVMExtensions.ClangFormat)也行。
有些东西(比如LAYOUT宏) 会被clang-format打乱， `//clang-format on` 之间装上会被搞乱的代码就好了。
# 一般教程
你可以给Q酱的不同部分添砖加瓦，
* 将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的最终归宿是键盘。有些键盘是社区维护的， 创建一个Issue ](https://github.com/qmk/qmk_firmware/issues ) 来问一问维护者。
我们建议你按下面的来操作:
* 用[模板](documentation_templates.md)写`readme.md`。
* 提交数量尽量合理，
* 不要把新特性和新键盘一起PR。可以分别PR他们
* 用父文件夹的名字命名 `.c` /`.h`文件, 比如`/keyboards/< kb1 > /< kb2 > /< kb2 > .[ch]`
* 键盘文件夹就不要放`Makefile`了，这个操作都过时啦
* 更新文件头部的copyrights(看`%YOUR_NAME%`那)
## Quantum/TMK 核心
在您废寝忘食地开发Q酱新特性或者帮Q酱驱虫之前， ， ：
* [在Discord交流 ](https://discord.gg/Uq7gcHh )
* [建立一个Issue ](https://github.com/qmk/qmk_firmware/issues/new )
新特性和BUG的修复影响所有键盘。开发组也在翻修QMK。所以， ， ，
修复BUG或者开发新特性之前看看这个：
* **默认不启用** - QMK运行的芯片多数内存有限， ， ， ，
* **提交之前在本地编译** - 这个简直就是家喻户晓了，但是也确实需要编译啊！ 我们的Travis系统会发现一切问题，
* **注意版本和芯片平台** - 有那么几个键盘有支持不同配置甚至是不同芯片的版本。试着写一个能AVR和ARM两个平台运行的特性，
* **解释你的新特性** - 在`docs/`写个文档, 你可以创建新文档或者写到现有文档中。如果你不把它记录下来，其他人就无法从你的努力中获益。
也可以看看以下建议：
* 提交数量尽量合理，
* 不要把新特性、布局和键盘一起PR。可以分别PR他们。
* 给你的特性写[单元测试](unit_testing.md)。
* 你编辑的文件风格要一致，如果风格不明确或者是混搭风的，你就要先看看[代码规范](#代码规范)确认情况。
## 重构
为了保持QMK脉络清晰， ，
# 行为守则对于我来说有何意义?
我们的[行为守则](https://github.com/qmk/qmk_firmware/blob/master/CODE_OF_CONDUCT.md) 是说明您有责任尊重和礼貌地对待项目中的每个人，无论他们的身份如何。 如果你是我们行为准则所描述的不当行为的受害者，我们将站在你这边，并按照行为准则对施暴者进行适当谴责。
