👍🎉 首先感谢各位百忙之中抽空阅读本文档,并为我们无私奉献。给您点赞啦! 🎉👍
第三方的帮助让Q酱成长了许多呢,Q酱也从你们那学到了不少新东西。Q酱希望每一个想帮助我的人都能很方便的做出有用的贡献。在这里我给摩拳擦掌的你们写了一点引导,让你们的代码在不对我做重大改动的情况下都能成功的被采纳哦。
您要是想问关于Q酱的问题的话可以在OLKB Subreddit或者是Discord随意问。
请记住:
Q酱很大一部分是用C语言组成的,不过有一小部分特性是C++的。怎么说呢,都是我的一部分,两个我都爱。Q酱一般是在键盘上的嵌入式处理器那里工作的,尤其与AVR(LUFA)和ARM (ChibiOS)两小哥哥搭配,干活不累,嘻嘻。如果您精通Arduino的话您会发现很多熟悉的概念,但也有点不爽,因为您以前的经验可能没法用来帮助Q酱。
您要是有问题的话可以 提出一个issue 或 在Discord上交流一下.
您以前是否没为开源贡献过代码,而又想知道帮助Q酱是怎么一回事? 稍安勿躁,咱给您总结一下!
你的GitHub用户名/qmk_firmware
就有一个仓库备份啦。git clone https://github.com/此处添GitHub用户名/此处添仓库名.git
这个命令把仓库同步到你的电脑中。git checkout -b 此处写分支名字(别用汉字)
命令来创建一个分支(branch)用于开发。git add 把改变的文件的目录写这里
可以添加改变的文件内容到git用于管理工程状态的索引(快照)里。git commit -m "这里写修改的相关信息"
来描述你做出了什么修改。git push origin 此处写分支名字
来把你的更改同步到GitHub库里(反正不是打篮球那个库里)。其实也没有什么特别严格的规范啦,但是俗话说的好:没有规矩,不成方圆。您可以看一下您的要改动的代码周围的画风,然后保持队形。如果你感觉周围都不知道是什么牛鬼蛇神的话就看看下面的建议:
/* */
#pragma once
放到头文件的开始哦,抛弃老土的(#ifndef THIS_FILE_H
, #define THIS_FILE_H
, ..., #endif
)吧#ifdef DEFINED
还有 #if defined(DEFINED)
#if defined(DEFINED)
。#if
。#
和 if
要挨在一起哦,再让本空格在中间冒充电灯泡本空格会生气的。可以参照下面:
/* foo 的 Enums*/
enum foo_state {
FOO_BAR,
FOO_BAZ,
};
/* 有返回值的情况 */
int foo(void) {
if (some_condition) {
return FOO_BAR;
} else {
return -1;
}
}
Clang-format 是LLVM的一部分,可以帮你自动格式化代码。我们给你准备好了一个适用于以上规范的配置文件,会帮你调整缩进和换行,你只需要写好括号就好。有了它,你再也不用担心调整代码格式太耗时,没有时间陪伴自己(虚构)的另一半了。
使用LLVM 完整安装可以在Windows上安装clang-format, Ubuntu用户要用sudo apt install clang-format
。
命令行的朋友们, 加上 -style=file
选项就会自动在QMK的根目录寻找.clang-format配置文件了。
VSCode用户, 标准的 C/C++ 插件就支持clang-format, 或者可以用独立扩展也行。
有些东西(比如LAYOUT宏) 会被clang-format打乱,所以那些文件就别用clang-format了,这里就教您一个小窍门,在// clang-format off
和 //clang-format on
之间装上会被搞乱的代码就好了。
你可以给Q酱的不同部分添砖加瓦,但也要用不同的方法严谨检查。不论你修改哪里最好还是看看下边。
git diff --check
的空格一定要写对了make keyboard:your_new_keymap
不返回错误make keyboard:all
不返回错误make all
不返回错误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酱当然是先看文档最简单了。找到这个文档哪里错了然后改正它对于你来说超级简单! 我们也对有写文档能力的人求贤若渴,如果你是对的人点这个!
文档呢,都静静的放在qmk_firmware/docs
目录里, 也或者您想为网页做贡献的话也是可以的哦。
在文档中附代码案例时, 先观察文档其他地方的命名规范。比如, 把enums的名字都改成像my_layers
或者my_keycodes
来防止名字不一致的enums被当作特务枪毙:
enum my_layers {
_FIRST_LAYER,
_SECOND_LAYER
};
enum my_keycodes {
FIRST_LAYER = SAFE_RANGE,
SECOND_LAYER
};
大多数QMK新手都从创建一个自己的布局开始。我们尽力保证布局规范宽松 (毕竟布局是个性的体现) 不过建议遵守以下准则,这样可以让别人更好理解你的代码
readme.md
。Makefile
了,这个操作都过时啦%YOUR_NAME%
那)QMK的最终归宿是键盘。有些键盘是社区维护的,有一些是制作这些键盘的人维护的。readme.md
会告诉你是谁维护了这个键盘,如果你对某个键盘有疑问,可以 创建一个Issue 来问一问维护者。
我们建议你按下面的来操作:
readme.md
。.c
/.h
文件, 比如/keyboards/<kb1>/<kb2>/<kb2>.[ch]
Makefile
了,这个操作都过时啦%YOUR_NAME%
那)在您废寝忘食地开发Q酱新特性或者帮Q酱驱虫之前,一定要确保你的工作是有意义的。看看了解QMK你会对Q酱有更深的了解,这个文档将带你领略QMK的程序流程。现在你应该和维护团对谈谈来了解实现你想法的最佳方法了。一下渠道都可以:
新特性和BUG的修复影响所有键盘。开发组也在翻修QMK。所以,在实施重大返修之前一定要讨论一下。如果你在没有事先与维护团队沟通的情况下提交了一个PR,而且你的选择与维护团队的计划方向不符,那你可能要面临大改了。
修复BUG或者开发新特性之前看看这个:
docs/
写个文档, 你可以创建新文档或者写到现有文档中。如果你不把它记录下来,其他人就无法从你的努力中获益。也可以看看以下建议:
为了保持QMK脉络清晰,Q酱打算深入规划重构一下自己,然后让合作者进行修改。如果你有重构的思路或建议创建一个issue, Q酱很乐意讨论一下怎么改进一下。
我们的行为守则 是说明您有责任尊重和礼貌地对待项目中的每个人,无论他们的身份如何。 如果你是我们行为准则所描述的不当行为的受害者,我们将站在你这边,并按照行为准则对施暴者进行适当谴责。