👍🎉 まず、これを読み貢献する時間を作ってくれてありがとうございます!🎉👍
サードパーティの貢献は、QMK の成長と改善に役立ちます。プルリクエストと貢献プロセスを貢献者とメンテナの両方にとって便利で簡単なものにしたいです。この目的のために、大きな変更をせずにプルリクエストが受け入れられるように貢献者向けのガイドラインをまとめました。
QMK について質問したい場合は、OLKB Subreddit あるいは Discord ですることができます。
以下の事を覚えておいてください:
QMK は主に C で書かれており、特定の機能と部品は C++ で書かれています。QMK は、キーボードの中の組み込みプロセッサ、特に AVR (LUFA) と ARM (ChibiOS) を対象にしています。すでに Arduino プログラミングに精通している場合は、多くの概念と制限がおなじみのものです。QMK に貢献するには Arduino を使用した経験は必要ありません。
助けが必要であれば、issue を開く か Discord で会話することができます。
以前にオープンソースに貢献したことはありませんか? QMK で貢献がどのように機能するかが疑問ですか? ここに簡単な説明があります!
GitHub上のあなたのユーザー名/qmk_firmware
の下にリポジトリのコピーを持つことを意味します。git clone https://github.com/GitHub上のあなたのユーザー名/repository-name.git
を使ってローカルマシンにリポジトリをクローンします。git checkout -b branch-name-here
を使って修正用の新しいブランチを作成します。git add insert-paths-of-changed-files-here
を使って変更されたファイルの内容を git がプロジェクトの状態を管理するために使用する "snapshot"、インデックスとしても知られている、に追加します。git commit -m "Insert a short message of the changes made here"
を使って、説明的なメッセージとともにインデックスの内容を保存します。git push origin branch-name-here
を使って GitHub 上のリポジトリに変更をプッシュします。私たちのスタイルのほとんどは簡単に理解できます。C あるいは Python のいずれかに精通している場合は、ローカルスタイルにそれほど問題はないはずです。
QMK には幾つかの異なるタイプの変更があり、それぞれ異なるレベルの厳密さが必要です。どのような種類の変更を行っても、次のガイドラインに留意してください。
git diff --check
を使って不要な空白を確認します。make keyboard:your_new_keymap
がエラーを返さないことを確認してください。make keyboard:all
がエラーを返さないことを確認してください。make all
がエラーを返さないことを確認してください。kerpleplork の fronzlebop を調整します
kerpleplork はエラーコード 23 で連続的に失敗していました。根本的な原因は fronzlebop 設定で、これにより kerpleplork はN回の繰り返しごとにアクティブになります。
私が使用できるデバイスの限られた実験では、kerpleplork の混乱を避けるために 7 は十分高い値であることを示していますが、念のため ARM デバイスを持つ人たちからフィードバックを得たいです。
!> 重要: デフォルト以外のキーマップ、ユーザスペースおよびレイアウトのようなユーザコードへのバグ修正あるいは改善に貢献したい場合は、PR にコードの元の提出者にタグをつけてください。Git と GitHub のスキルレベルに関係なく、多くのユーザは知らないうちにコードが変更されることに混乱したりイライラしたりするかもしれません。
ドキュメントは QMK への貢献を始める最も簡単な方法の1つです。ドキュメントが間違っているか不完全な場所を見つけ、これらを修正するのは簡単です!私たちもドキュメントを編集する人を非常に必要としています。編集するスキルがあるが、どこにどのように飛び乗ればいいのか分からない場合は、助けをもとめてください!
全てのドキュメントは qmk_firmware/docs
ディレクトリの中にあります。あるいは web ベースのワークフローを使いたい場合は、https://docs.qmk.fm/ の各ページの下部にある "Edit this page" リンクをクリックすることができます。
ドキュメントの中にコードの例を提供する場合は、ドキュメント内の他の場所で使用されている命名規則を順守してください。例えば、一貫性を保つために、my_layers
あるいは my_keycodes
として列挙型を標準化します:
enum my_layers {
_FIRST_LAYER,
_SECOND_LAYER
};
enum my_keycodes {
FIRST_LAYER = SAFE_RANGE,
SECOND_LAYER
};
開発環境をセットアップした場合は、プルリクエストを開く前に以下のコマンドを qmk_firmware/
フォルダから実行することで、あなたの変更をプレビューすることができます:
./bin/qmk docs
または、Python 3 のみがインストールされている場合:
python3 -m http.server 8936
その後、ウェブブラウザで、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 のプログラムフローのツアーに連れて行きます。ここから、あなたのアイデアを実装するための最良の方法の感覚をつかむために、私たちと話す必要があります。これを行うには主に2つの方法があります:
機能とバグ修正の PR は全てのキーボードに影響します。また、私たちは QMK の再編も進めています。このため、実装が行われる前に特に重要な変更について議論することが特に重要です。最初に私たちと話をせずに PR を開いた場合、あなたの選択が私たちの計画した方向とうまく合わない場合は幾つかの大きな再作業を行う覚悟をしてください。
機能やバグの修正に取り組む時に留意すべき幾つかの事があります。
docs/
の中に文章化します。文章化しないと、他の人はあなたの苦労から利益を得ることができません。また以下のガイドラインに従うことをお願いします:
QMK で物事がどのようにレイアウトされるかについて明確なビジョンを維持するために、私たちはリファクタリングを詳細に計画し、変更をする協力者がいます。リファクタリングのアイデアあるいは提案がある場合は、issue を開いてください。QMK を改善する方法についてお話ししたいと思います。
私たちの行動規範は、身元に関係なくあなたがプロジェクトの全員を敬意と礼儀を持って扱う責任があることを意味します。あなたが行動規範に記載されている不適切な行動やコメントの被害者である場合は、私たちはあなたのためにここにおり、私たちのコードに従って虐待者が適切に懲戒されるように最善を尽くします。