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

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

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

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

# 開発の流れ

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】コミットはせずに変更を退避したいとき](https://qiita.com/chihiro/items/f373873d5c2dfbd03250)）。


## リモートリポジトリで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ブランチを切り直せば大丈夫です。
思いのままのアイデアをコードにしてください。:blush:

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

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

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

コミットメッセージのフォーマットは、`[コミット種別] #対応するPR番号 要約`としてください。コミット種別は以下の四種類を使ってください（参考：[Gitのコミットメッセージの書き方](https://qiita.com/itosho/items/9565c6ad2ffc24c09364#%E9%80%9A%E5%B8%B8%E7%89%88)）。

* fix
* add
* update
* remove

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

# レビュー

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

どれだけ細かくレビューをするかは時と場合によりますが、ちゃんとレビューをして、レビューの通ったコードだけが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]を押してください。

<img width="752" alt="qiita_github_pr_1.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/127680/ed8f9f58-18e4-794c-5cfa-0aa5b4f735f7.png">

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

<img width="569" alt="qiita_github_pr_2.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/127680/a3e607e4-fae1-3950-5bf4-4ce3f928e90b.png">

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

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

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

<img width="576" alt="qiita_github_pr_4.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/127680/8159a83a-5079-5f1f-05dd-f7f9a1ecc538.png">

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

<img width="621" alt="qiita_github_pr_5.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/127680/e4fcc0ec-8805-f6a0-65aa-1dce0a76a052.png">

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

<img width="623" alt="qiita_github_pr_6.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/127680/4173e160-1d4a-cd3f-b6e3-62abf33a9a02.png">

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

<img width="599" alt="qiita_github_pr_7.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/127680/17049b84-e311-b4eb-938b-9585b7774ef3.png">

# 最後にmasterブランチへmerge

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

<img width="568" alt="qiita_github_pr_8.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/127680/cbf5f374-c84d-1706-dfc1-dd232e027e33.png">

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

# おわり

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

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