Githubでチーム開発するためのマニュアル

チームでkaggleやることにしました。

この記事では誰でも迷わずチーム開発に参加できるよう、チーム開発の流れをマニュアル化することだけを目的にします。
複雑な使い方とかはなしです。必要に応じて応用編の別記事を書きます。

チームのみなさんの助けになれば幸いです。

開発の流れ

Githubで管理するリポジトリでは、以下の流れでコードを更新します。

• まずはmasterブランチからはじめる
  • ローカルリポジトリでmasterブランチに入る
  • リモートリポジトリでmasterブランチの更新があるか確認する
• featureブランチで開発
  • featureブランチを切る
  • 開発する
  • 変更点をローカルリポジトリでcommitする
• レビュー
  • リモートリポジトリへpushする
  • Pull Requestを出す
  • PRでレビューをしてもらう
• 最後にmasterブランチへmerge
  • PRのレビューが終了したら、masterブランチへmergeする

以下、各手順ごとに説明します。

まずはmasterブランチからはじめる

masterブランチには、信頼できるコードやドキュメントがまとめられています。
何をするにもmasterブランチが基本ですし、信頼できないコードやドキュメントをmasterブランチに入れてはいけません。

ローカルリポジトリでmasterブランチに入る

git checkout master

これだけです。
単純ですが、ちゃんとしたPRを出す・コンフリクトを防ぐためには必須です。

とにかく、コードを変更したくなったら、必ず一度masterに戻ってからブランチを切り直す癖をつけてください。

この一行を忘れて変なブランチから開発することで、コミット履歴がめちゃくちゃになります。git pullもgit diffも使い物にならなくなります。コンフリクトを退治してたら日が暮れたとか悲惨なことになります。忘れないでください。

PR上のFiles changedがやたらと多いときなどは、masterに戻るのを忘れている可能性が大です。そうでない場合はひとつのブランチに作業をまとめすぎです。いずれにせよ、コミット履歴がめちゃくちゃだとあなたのコードを読む人が疲れてしまうので、気をつけてください。

とはいえ、つい変な変更をしてしまい、masterに戻れなくなることもあります。

masterに戻れない場合はgit stashで作業を待避してからもう一度git checkout masterしてください。git stashで差し戻した変更点はあとで追うことができます（参考：【git stash】コミットはせずに変更を退避したいとき）。

リモートリポジトリでmasterブランチの更新があるか確認する

git pull

チーム開発をしていると、自分のあずかり知らぬところでmasterブランチが更新されていることがあります。そのようなときに古いmasterブランチからfeatureブランチを作るとコンフリクトが起きかねないので、更新を確認する必要があります。git checkout masterとあわせて習慣にしてください。

ちなみに、ブランチを切ったあとにmasterが更新されてしまうことがあります。そういう場合はgit rebaseをして、最新のmasterとfeatureブランチを一本化してください。

featureブランチで開発

masterブランチでは、あらゆるコードの追加や変更をしないようにしましょう。
一行でもなにかコードを書こうと思ったら、featureブランチという開発用ブランチで書いてください。

featureブランチを切る

git checkout -b feature/new-branch

このコマンドでは以下の２つの動作を実行します。

• feature/new-branchブランチを作る
• feature/new-branchブランチに移動する

masterブランチから自動的に移動してくれるので、git branchを実行して確認してみましょう。

なおfeatureブランチを作る際には、名前をfeature/xxxとしてください。
ブランチの命名法には諸説あるかもしれませんが、チーム内ではこの規則に従ってください。

開発する

featureブランチの変更内容は、masterブランチには反映されません。

どれだけバグのあるコードを書いたとしても、masterブランチにあるファイルは影響を受けません。誤って大切なコードやファイルを消してしまい、スクリプトが動作しなくなったとしても、masterブランチには正常に動作するファイルが残っています。

やってしまったと思ったら、一度masterブランチに戻ってfeatureブランチを切り直せば大丈夫です。
思いのままのアイデアをコードにしてください。

変更点をローカルリポジトリでコミットする

git add test
git commit -m "[add] #1 新規モデルでsubmission"

追加・変更したファイルをgit addで指定し、その後git commitで変更を保存します。

コミットメッセージのフォーマットは、[コミット種別] #対応するPR番号 要約としてください。コミット種別は以下の四種類を使ってください（参考：Gitのコミットメッセージの書き方）。

• fix
• add
• update
• remove

あとは、__pycache__や*.ipynbといったGit管理の邪魔になるファイルをgit addの対象に含めないようにしてください。安易にディレクトリやワイルドカードを指定しない、gitignoreを書くといった方法で対処してください（参考：.gitignore の書き方。ファイル/ディレクトリの除外と反映方法）。

レビュー

チーム開発で大切なことは、メンバーがお互いにレビューしあうことです。

どれだけ細かくレビューをするかは時と場合によりますが、ちゃんとレビューをして、レビューの通ったコードだけがmasterブランチにmergeされるようにしましょう。

リモートリポジトリへpushする

git push origin feature/new-branch

Githubのリモートリポジトリへ、ローカルリポジトリの変更を反映させます。
これでPRを出したり、他の人があなたの更新したコードを見えるようになります。

masterブランチへはpushしないでください。git push -f origin master**は絶対に使わないでください。**masterブランチは保護してるつもりですが、うっかり通るかもしれません。

Pull Requestを出す

Github上のリポジトリページに飛びます。
すると、pushしたブランチのPull Request (PR)を出せるようになっています。
画面右の[Compare & pull request]を押してください。

すると、PRを作成する画面に飛ぶので、以下の手順で編集・作成してください。

1. Reviewerを指定する
2. タイトルを[ブランチ名] 要約とする
3. 最低限の概要とmergeを受け入れる条件を書く
4. [Create pull request]を押す

Pull Requestでレビューする・してもらう

[Pull request]タブを開くと、先程開いたPRが出来ています。

PRでは、[Files changed]を押すと、ファイルの変更点を見られる画面に遷移します。
各行にマウスカーソルを合わせると、"+"ボタンが出てくるのでレビューしたい箇所でクリックします。

レビューを書き、[Start a review]をクリックします。
この状態ではレビューはまだ保留されています。保留されている間に、他の行でもレビューしたいことがあれば、同様に書きましょう。

[Finish your review]を押すと、保留中のレビューを解決する画面が出てきます。
ここに総括的なコメントを書くと、PRの[Conversation]タブの方に反映されるので、必要に応じて書いてください。特にmergeしてもよい、と判断したときは、"+1"とコメントして、ラジオボタンから[Approve]を推してください。
最後に[Submit review]を押すと、これまでのレビューが解決されます。

最後にmasterブランチへmerge

PRの[Conversation]タブを開き、一番下の[Squash and merge]をクリックしてください。[Squash and merge]がない場合は、▼を押してプルダウンから選択してください。

これでmasterブランチにあなたの書いたコードが反映されました。

おわり

間違ってるところとか穴とかあるかもしれません。
そういうときは書き直す場合があると思います。

この記事の性質は不特定多数のみなさまが参照する信頼できる情報源というより、
チームのメンバーのためのマニュアルが公開されてるだけ、という感じなので、ご容赦ください。