この文書では、コマンドラインから git を使って qmk_firmware をクローンして、ブランチを作ってプルリクエストを出す手順の概要を説明しています。
本文書を読んだあとで qmk_firmware のドキュメントの以下のものにも目を通して置くとより一層理解が深まると思います。
以下の順に実行します。
やり方の詳細はこの文書では省略します。参考資料を探して参照してください。
0-2. https://github.com/qmk/qmk_firmware をフォークする。
やり方の詳細はこの文書では省略します。参考資料を探して参照してください。
以下を実行します。
$ git clone https://github.com/MY_ACCOUNT/qmk_firmware
$ cd qmk_firmware
この時点で、手元(のPC)に qmk_firmware リポジトリが出来上がり、この
リポジトリの中では、親リポジトリ(GitHub 上の自分のアカウントの qmk_firmware リポジトリ)は、origin という名前になります。
手元(のPC)の qmk_firmware リポジトリから参照できるように、フォーク元の QMK の qmk_firmware リポジトリをリモート登録します。
(既に $ cd qmk_firmware したものとします)
$ git remote add qmk https://github.com/qmk/qmk_firmware
この時点で、手元(PC)の qmk_firmware リポジトリの中では、フォーク元の QMK の qmk_firmware リポジトリの名前は、qmk になります。
確認してみましょう。
$ git remote -v
origin https://github.com/MY_ACCOUNT/qmk_firmware (fetch)
origin https://github.com/MY_ACCOUNT/qmk_firmware (push)
qmk https://github.com/qmk/qmk_firmware (fetch)
qmk https://github.com/qmk/qmk_firmware (push)
実は フォーク元のリポジトリの名前は、upstream をつけるのが慣例です。
他の資料をみると、そうなっている例が多数あります。
しかしここでは、名前が指している対象がわかりやすい qmk ですませます。
QMK のリポジトリのブランチ情報を取得しておきます。
$ git fetch qmk
ブランチのリストを見てみましょう。自分のアカウントのリポジトリのマスターブランチ origin/master と QMK のリポジトリのマスターブランチ qmk/master があることが確認できます。
$ git branch -a
* master
remotes/origin/HEAD -> origin/master
remotes/origin/master
remotes/qmk/master
その他ごちゃごちゃ沢山
以後、自分のリポジトリの master ブランチは、QMK の qmk_firmware リポジトリの master ブランチと履歴も含めて同一になるように運用する方針とします。
つまりローカルでは master ブランチへの commit、または他のブランチから master ブランチへの merge はやらないことにします。
前節の最後の手順の直後では、QMK, 自分のアカウントのフォーク、手元(PCの)それぞれの master ブランチは同じ履歴になります。しかし QMK にあらたなコミットが追加されると、QMK の master の履歴はのびていきます。
こうなったとき、自分のアカウントの qmk_firmware リポジトリ、手元(PC)の qmk_firmware リポジトリは、おいてけぼりになります。これは自分で同期させなければなりません。 GitHub には、フォークした自分のリポジトリと元のリポジトリを同期させる直接の手段は用意されていません。
以下の手順で、定期的に、あるいは必要なときに手動で同期をさせます。
手元(PC)の qmk_firmware リポジトリに、フォーク元のリポジトリの新しい情報(コミット等)を取り込み、それを GitHub 上の自分のアカウントの qmk_firmware リポジトリに push してやる必要があります。
フォーク元のリポジトリの新しい情報(コミット等)を取り込みは以下のように行います。
(既に $ cd qmk_firmware してあるものとします)
(既に $ git checkout master してあるものとします)
$ git pull qmk master
そして、GitHub 上の自分のアカウントの qmk_firmware リポジトリに push します。
$ git push origin master
確かめてみましょう。
$ git log --graph --pretty=oneline --abbrev-commit --decorate
* 9ea9806d6 (HEAD -> master, tag: 0.7.89, qmk/master, origin/master, origin/HEAD) Set up language fallback for docs, and update translation guidelines (#7403)
* 7874f297b (tag: 0.7.88) Remove CR when computing BOOTLOADER_SIZE. (#7453)
* 3541f01a7 Update led_update_kb example (#7451)
* eae21eed7 [Keymap] Adding hbbisenieks keymap for keebio/iris (#7440)
* e62ab7e25 Allow overriding of all functions in wonderland.c (#7198)
* 0270d4d5a [Keymap] changed knight ridder offset to face me on planck (#7445)
* 7e9ed2acb (tag: 0.7.87) Fix clang-format logic within CI (#7386)
* 66d473437 (tag: 0.7.86) Improve and streamline MSYS2 installation (#7232)
以下略
qmk_firmware に自分のキーマップやキーボードを追加する、ドキュメントの日本語訳を追加する、ドキュメントの改訂をする、などの作業をする場合は、master ブランチから分岐した別のブランチを作ってその上で作業を進めます。こういった、特定のテーマの変更のために作るブランチをトピックブランチと呼ぶことがあります。
トピックブランチの名前は、変更事項を表わす名前をつけると良いです。
例えば、XXX機能の追加であれば add_XXX_function のように、また例えば、YYYドキュメントの修正、であれば、update_YYY_document のように。
(実は、qmk_firmware の Core 部分、quantum/, tmk_core/, drivers/, platforms/, lib/ などに変更を加える場合は、master ブランチではなく develop ブランチから分岐するのですが、このケースはより上級な話題なので、この文書では取り扱いません。
PR チェックリスト や 互換性を破る変更/Breaking changes を参照してください。)
トピックブランチを分岐させるポイントを決めます。
前の節 QMK の qmk_firmware リポジトリとの同期のとりかたで示した方針通り qmk の master と自分の master が一致している場合は、最新の状態に同期させたあと master を分岐ポイントとするのが良いでしょう。
以下の様にします。
(既に $ cd qmk_firmware してあるものとします)
$ git branch update_YYY_document master
$ git checkout update_YYY_document
もしも、qmk の master と自分の master が不一致の場合は、qmk が履歴の要所要所でつけているタグを分岐ポイントとすると良いでしょう。
まず qmk の最新状態を取得します。
(既に $ cd qmk_firmware してあるものとします)
$ git fetch qmk
そして最新のタグをさがします。
$ git log --graph --pretty=oneline --abbrev-commit --decorate qmk/master
* 9ea9806d6 (tag: 0.7.89, qmk/master) Set up language fallback for docs, and update translation guidelines (#7403)
* 7874f297b (tag: 0.7.88) Remove CR when computing BOOTLOADER_SIZE. (#7453)
* 3541f01a7 Update led_update_kb example (#7451)
* eae21eed7 [Keymap] Adding hbbisenieks keymap for keebio/iris (#7440)
* e62ab7e25 Allow overriding of all functions in wonderland.c (#7198)
* 0270d4d5a [Keymap] changed knight ridder offset to face me on planck (#7445)
* 7e9ed2acb (tag: 0.7.87) Fix clang-format logic within CI (#7386)
* 66d473437 (tag: 0.7.86) Improve and streamline MSYS2 installation (#7232)
以下略
(tag: 0.7.89, qmk/master) という表示があるので、0.7.89が最新でした。以下の様にしてトピックブランチを作ります。(無理に最新でなくても、0.7.88 や 0.7.87 などの十分最近のものでも構いません)
(既に $ cd qmk_firmware してあるものとします)
$ git branch update_YYY_document 0.7.89
$ git checkout update_YYY_document
必要なだけファイルの編集とコミットを繰り返します。
$ edit file
$ git add file
$ git commit
以下のようにします。
(既に $ cd qmk_firmware してあるものとします)
$ git push origin update_YYY_document
作成した、update_YYY_document ブランチをプルリクエストします。
やり方の詳細はこの文書では省略します。参考資料を探して参照してください。
GitHubのヘルプ - プルリクエストで、作業に対する変更を提案する
GitHubのヘルプ - プルリクエストの作成方法
プルリクエストを出した後も、マージされる前ならば追加の変更は可能です。
「トピックブランチにコミットする」 と 「トピックブランチをoriginに push する」 を繰り返してください。自動的にプルリクエストのなかに追加されます。
プルリクエスト上でレビュアーから修正要求があったら、上の手順で変更を追加します。
また、プルリクエスト中にレビュアーから提案された変更を GitHub 画面上で、Commit suggenstion ボタンを押して採用することも出来ます。この場合、GitHub上でコミットが作成されるので、手元のリポジトリに取りこむ必要があります。
以下のようにします。
(既に $ git checkout update_YYY_document してあるものとします)
$ git fetch origin
$ git rebase origin/update_YYY_document
プルリクエストがマージされたら、master ブランチの同期 をしておくと良いでしょう。
用がすんだら、トピックブランチを消します。
GitHub 上の自分のアカウントの qmk_firmware リポジトリ origin のブランチを消します。
$ git push --delete origin update_YYY_document
手元のリポジトリのブランチも消します。
(後で、細かい履歴を参照したくなった時のこと考えて消す前にタグを振っておきます。以下の例では、タグの名前は prlog/update_YYY_document です。)
$ git checkout master
$ git tag prlog/update_YYY_document update_YYY_document
$ git branch -D update_YYY_document
これはlib/vusbサブモジュールのほうの更新があったためです。gitのコマンドでサブモジュールを更新するか、qmkなら
make git-submoduleとすれば同じことができます