👍🎉 首先感谢各位百忙之中抽空阅读本文档,并为我们无私奉献。给您点赞啦! 🎉👍
第三方的帮助让QMK获得了成长与进步。我们希望提供一套对贡献者和维护者都感到简便实用的PR(pull request)及贡献流程,因此我们整理出了一些准则,以免你的PR在被接纳前需要大改一番。
您要是有关于QMK的问题,请在OLKB Subreddit或者是Discord上进行提问。
请记住:
QMK很大一部分是C语言编写的,小部分特性是C++的。QMK的设计目标是在键盘上的嵌入式处理器中工作,如AVR(LUFA)和ARM (ChibiOS)。如果您对Arduino很熟悉的话,会发现优缺点也基本是相似的。但无论你之前是否有Arduino使用经验,都不会影响你参与到QMK贡献中来。
您要是有问题的话可以 提出一个issue 或 在Discord上交流一下.
您以前是否没有参与贡献过开源社区,而又想知道如何对QMK提供帮助?这里有一份快速指引! 译注:对于没有基本编程经验的人,请谨慎考虑这套操作流程,可参考,照着做很容易出问题,社区的语言障碍也会阻碍你对这些步骤的细节进行咨询
你的GitHub用户名/qmk_firmware
下就有一个副本啦。git clone https://github.com/你的GitHub用户名/仓库名.git
命令把仓库同步到你的电脑中。git checkout -b 此处写分支名字(别用汉字)
命令来创建一个新分支(branch)用于开发。git add 把改变的文件的目录写这里
可以添加改变的文件内容到git用于管理工程状态的索引(快照)里。git commit -m "这里写修改的相关信息"
来描述你做出了什么修改。git push origin 此处写分支名字
来把你的更改同步到GitHub库里(反正不是打篮球那个库里)。我们的编码风格很容易掌握,如果你有C语言或Python编码经验,跟随我们的编码风格不会有什么困难。
在QMK中存在多种类型的修改需求,因此也会有审查严格性上的差异。请在做出任何修改时留意,你的改动隶属于什么类型。
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.
!> 特别留意: 若你要对其它QMK使用者提交的代码进行功能修改或尝试修复bug,例如非默认的键映射、用户空间和配列部分,须在PR中标记出代码的原始提交者。很多QMK使用者都会对自己提交的代码在不知晓的情况下产生了改动感到困惑和沮丧,无论他的Git及Github经验丰富与否。
对文档进行修正是最简单的参与贡献的一个办法,找到错误放置的文档或是修复不完备的部分很容易!我们也急需能修订文档的贡献者参与进来,所以如果你具备这样的能力但不清楚如何开始,请看这里!
文档位于 qmk_firmware/docs
目录下,如果你习惯于在web页面中完成工作目标,可以在 https://docs.qmk.fm/ 各文档页面下方点击“Edit this page”在线进行编辑。
在文档中附代码案例时, 先观察文档其他地方的命名规范。比如, 将enum类型的定义命名为 my_layers
或 my_keycodes
的形式可以保持前后一致性:
enum my_layers {
_FIRST_LAYER,
_SECOND_LAYER
};
enum my_keycodes {
FIRST_LAYER = SAFE_RANGE,
SECOND_LAYER
};
在发起pull request前,请通过文档预览来检查你的本地更改。可以在 qmk_firmware/
目录下执行以下命令来配置文档开发环境:
qmk docs
或者,如果你有安装Python 3,可以尝试:
python3 -m http.server 8936 --directory docs
然后在本地浏览器打开 http://localhost:8936/
.
大多数QMK新手都从创建一个自己的键映射 开始。我们尽力保证键映射规范宽松 (毕竟键映射体现的是个人喜好) 不过我们仍要求须遵守以下准则,以便他人更好地发现并理解你的键映射代码。
readme.md
。Makefile
文件(已不再使用)%YOUR_NAME%
部分)QMK的最终归宿是键盘。有些键盘是社区维护的,有一些是制作这些键盘的人维护的。readme.md
会告诉你是谁维护了这个键盘,如果你对某个键盘有疑问,可以 创建一个Issue 来问一问维护者。
我们建议你按下面的来操作:
readme.md
。.c
/.h
文件, 比如 /keyboards/<kb1>/<kb2>/<kb2>.[ch]
Makefile
了,这个操作都过时啦%YOUR_NAME%
那)在你投入大量精力到新功能开发中之前,请先确保使用了最佳的实现方案。通过阅读了解QMK可以获得对QMK的基本认知,这个文档将带你领略QMK的程序流程,然后你可以和维护团队探讨一下实现你想法的最佳方法的思路,以下渠道都可以:
新特性和BUG的修复影响所有键盘,开发组也在翻修QMK。所以,在实施重大改动之前一定要讨论一下。如果你在没有事先与维护团队沟通的情况下提交了一个PR,而且你的选择与维护团队的计划方向不符,那你可能要面临大改了。
修复BUG或者开发新特性之前看看这个:
docs/
写个文档, 你可以创建新文档或者写到现有文档中。如果你不把它记录下来,其他人就无法从你的努力中获益。也可以看看以下建议:
为了保持QMK脉络清晰,QMK的深度重构工作已在规划中,并会通过合作者进行相应的修改。如果你有重构的思路或建议请创建一个issue, 我们很乐意讨论一下QMK可以如何改进。
我们的行为守则 指出您有责任尊重并礼貌地对待项目中的每个人,无论他们的身份如何。如果你是我们行为守则所描述的不当行为的受害者,我们将站在你这边,尽最大努力对施暴者进行谴责。