なにこれ
普段お世話になっているgithubをもっと便利に使うために思っているところを雑に書く。
会社でまとめた内容が割とウケが良かったので知見の棚卸し。
設定編
ブランチの保護（削除対策編）
人間はミスをする生き物です。
「うっかりミス」が発生することがままあるでしょう。
でも、そんな「うっかりミス」のせいで、稼働中のサービスにデプロイやCI/CDしているブランチを消してしまった場合、大変マズイことになります。
サービスの規模や時間によるとは思いますが、ちょっと前の職の例ではホットタイムだと毎秒n万円の損失が発生することになるので冗談抜きでマズイことになります。
ということで、間違って消しちゃうことがないように重要なブランチは保護してあげましょう。
やり方
- 保護したいブランチのgithubページを開く
-
Settings>Branches>Protected branchesを開く-
Branch protection rulesと出ている場合はAdd ruleボタンを押せばOK - 認証ページに飛ばされた場合はパスワードを入れる
-
-
Apply rule toというところで保護したいブランチを指定
- 一応この段階でブランチの保護はOK。「うっかりミス」は最低限防げるはず
ブランチの保護（未レビューなプルリクエストのマージ対策編）
削除に対しての保護は上の対応で基本的にはOKです（やろうと思えばこれでも消せるけど）。
ただ、ブランチは削除だけでなく、危険なマージからも保護しないといけません。
やり方
ブランチの保護設定画面でProtect matching branchesの下にRequire pull request reviews before mergingという項目があります。
これはプルリクエスト（以降：PR）のマージをする際に、レビュアーからの承認をもらっていない場合はマージできなくするという保護設定です。
これを設定すると、PRの画面で
というようにCircleCIのチェックとは別に、マージにロックをかけてくれます（CircleCI使ってない場合は項目が2個になります）。
承認要求人数や必須承認者（この人の承認がないとロック）の設定、コミットがあるたびに再承認を要求するなどの設定で、よりきめ細かな承認ルールを定義できます。
余談
開発の優先度やチーム内の指針で利用するかどうかが決まってくる内容だとは思いますが、僕個人としてはレビュアー：1名の設定がベターかなと思っています。
- チーム開発の場合、ここの設定が0名は基本的には無しかなーと思ってます。
- だったらPR出さないでマージしちゃいなよって思っちゃいます。
- エビデンス残すためっていうのはわかるけど
- ここが2名以上になると開発速度が落ちていきます（承認待ちになりやすくなるので）
- というか多人数になればなるほど、なぁなぁでマージすることが多くなるので、多人数は逆に製品の品質が落ちていくような気がしています
- その昔、必要承認数3だった時、PRが永遠にマージされない現象が起きて爆死したことがあります
その他にも細かい設定ができるので調べてみて、チーム内でルール策定ができるといいと思うよ。
ブランチの保護（master直push対策編）
そうなんですよね。
githubは強制mergeは防げるけど、直pushは防げないんですよね・・・。
ということで以下を参考に。
FYI: 特定ブランチのgit push origin masterを禁止する
要は
- 保護したい対象の
.gitフォルダにhook用のファイルを作成 - 保護したいブランチを指定
- 各個人が各々設定する必要がある
という内容。
最後が特に重要。
対応としては、以下のような感じにすればOKです。
必要に応じて対象を増やしたり減らしたりしよう。
$ cat "プロジェクトディレクトリ"/.git/hooks/pre-push
#!/bin/bash
while read local_ref local_sha1 remote_ref remote_sha1
do
if [[ "${remote_ref##refs/heads/}" = "master" ]]; then
echo "Do not push to master branch!!!"
exit 1
elif [[ "${remote_ref##refs/heads/}" = "develop" ]]; then
echo "Do not push to develop branch!!!"
exit 1
fi
done
テンプレート編
githubはPRやissueにテンプレートを入れることができます。
これを導入することで
- 毎回PRやissueで文言や項目を考えるのが面倒
- メンバー個々人に任せたりすると、人によって説明の粒度がばらつき出る
- ある程度放置されたPRを見たときに、なんのための修正・更新なのかが理解できなくなる
そもそもPRが放置されている事象自体が異常事態とかいうツッコミはさておき
という問題が解決され、ある程度製品の品質が保たれます。
是非入れましょう。
やり方
テンプレートを入れたいブランチに.githubというフォルダを作成。
- PULL_REQUEST_TEMPLATE.md：PRのテンプレート
- ISSUE_TEMPLATE.md：issueのテンプレート
- CONTRIBUTING.md：Contributeのテンプレート（社内開発だとあまり出番ないかも？）
を作成。以上。
ここで書いたMarkdownがそのままPR / issue作成時に埋め込まれます。
サンプル：
超便利。
そのなかで必要なものだけ使えばいいと思う。
例： https://github.com/mochisuna/issue-template-sample/pull/1
ちなみに、テンプレートは複数用意することもできて、要件に合わせて切り替えるなんていう運用もできてしまう！！！
FYI: GitHub の Issue Template を複数設定して使い分ける
ありがたやー。
個人的な見解
- 実装の背景・目的
- やったこと
は基本的に欲しい項目。
PRを出してまで機能を作成したということは、そこに至る背景（もっと言えばニーズ）があるはずなので、レビューする側からすれば「なんのためにこれやったんですか？」ということを説明して欲しいところです。
下手に省略するよりも、最終的にはその方が効率的です。
ただ、毎回書くと、それはそれで手間というのはわかるのでチーム内で方針が共有できてればいいんじゃないかなぁ・・・。
後は緊急時対応で承認待ってられない場合どうするのか問題はありますね。
おそらく設定を一時的に外してもらう形になるのかなぁ・・・。
緊急時だからしょうがない・・・よね？
・・・というかそんな自体が頻発する場合は何かがおかしい。
ちゃんとレビューしてって話になる。
ブランチ運用編
個人的にはほぼ2択だと思っています。
FYI：git flowとgithub flowとは？その違いは？
- git flow
- github flow
個人的な見解としては（雑すぎて色々ツッコミもらいそうだけど）、
- 開発を早めてガンガンリリースしていきたい場合はgithub flow
- ある程度製品ができてきたらgit flow
という使い分けかなー？って思ってます。
CCIでCI/CDすることを考えるとgit flowの方が何かと安全な気がしている（ここは気のせいな可能性が高い）。
後、branchにも命名規則があった方がいいですね。
- feature/hogehoge
- bugfix/hogehoge
- hotfix/hogehoge
とかで、「なんのための開発なのか」を明記するように名前付けしてあげると
- どういう意図でブランチを切ったのか
- どのブランチが優先度高いのか
などがわかりやすくなるので大変good。
ちなみに末尾を/にしておくとgit clientによってはディレクトリ形式で解釈してくれるので、ちょっとイケメン。
プルリクエスト編
ここに関してはチームの文化次第な側面が多いと思います。
- PRのタイトルにprefixとして
[WIP]、[IR]、[Bugfix]という文言をつけてステータス管理 - PRラベルでステータス管理
- 男気一本、つうと言えばかあで解決
・・・など。
なので、個人的にはラベルで管理したい気持ちがあるけれど、一概にこれがいいとかこうじゃないとだめとかは深く掘らないようにします。
チームで話し合って決めましょう。
なんにせよ一律して言えることは
- マージ済みのブランチは必ず消す
-
PRは基本的にマージするか棄却する
- どちらもしないで放置するのは一番ダメ
というルールはあった方がいいですね。
マージ済みのブランチを消さずに放置した結果、名前の重複や似た名前のブランチを間違ってcheckoutしちゃったり、
出したPRを誰も見ないでずっと放置した結果、PR同士がコンフリクトしまくる、あるいはそもそも状況が変わってPR自体が不要になることがあるので・・・。
必要なものだけ残そうぜ！
個人的に良いと思ったルール
生煮えPR
ここの資料でも言及されてるルールです
FYI: https://speakerdeck.com/ken_c_lo/pull-request-4-designers-githubwoshi-tutapuroguramatodezainafalseitereteibunakai-fa-huro?slide=11
要点としては、
- 機能的には不完全だけど早い段階でPRとして出してしまう
- 「こういう風にしたいけどどうする？」みたいなのを議論しながら進める
- 早い段階で進め方レベルでの間違いや方針について修正できる
といったもので、内容がふわっとしているものや技術的に難しいもの、規模が大きくなりそうなものなどを進めるにあたり便利です。
コードの進め方に困った際にも有用で、よく使っています。
[WIP]という接頭語をPRに入れるかタグを用意しちゃうのが良い感じある。
コメントルール
コメントを入れる際に、どういう意図なのかを接頭語で書いてしまうやり方です。
FYI: 英語のコメントや issue で頻出する略語の意味 (FYI, AFAIK, ...)
・・・よく考えたらこのFYI自体が該当しますね。
何を思ってのコメントなのかが明確になるのでとってもよさみが深い。
特に、このコメントは ただの文句じゃないよね？ とか、 僕ならこうするよ みたいなのを自分で確認してから投稿できるのがいいなと思います。
余談というかどうでも良い内容ですけど、僕の場合
- imo
- MUST
- ask
- nits
- FYI
がよく使うワード。
なぜか大文字小文字がごちゃまぜ。
統一しよ・・・。
拡張を入れてもっと良い感じに使いたい編
正直これが言いたかった。
Octotree
今回紹介する商品はこちら、Octotree。
階層状にブランチを表示してくれる。
例：普段お世話になってるKarabiner-Elements様の場合
しかも、PRの場合は差分があるファイルだけ出してくれる。
とっても便利！
Refined GitHub
続いてこちら、Refined GitHub。
GitHubの表示をいい感じに変えてくれたり、追加機能として直近マージされたブランチのPRを出せたりするようになります。
機能が多く、詳しくはREADMEを見た方が良いのですが、とりあえず痒いところに手が届きまくるので大変便利。
↑アイコンも可愛い。
余談：PRマージ後のブランチ削除はOSSのアプリでもあったりします
FYI: Delete merged branch
その他
Activity overview
（2018年9月現在）最近追加された機能です。
その人がgithub上でどんなことをやってきたのかを４種類のデータでグラフ化してくれます。
- Code review
- Issues
- Commits
- Pull requests
どれが伸びてると良いとかではなく、その組織においてどういう貢献をしているかが重要かなと思っています。
僕の場合、本業では
レビューしないおじさん。
別の組織では、
文句ばっかりおじさん。
みたいなのがよくわかります。
まとめ
- githubはとっっっっっても便利。だからもっと便利に使おう。
-
運用で頑張るは頑張れない未来しか待っていないので、人間の手が介在しにくい運用フローがいいですよね。 - 拡張とかテンプレとか、使えるもんは使ったもん勝ち。
参考・引用した記事
- 特定ブランチのgit push origin masterを禁止する
- GitHub の Issue Template を複数設定して使い分ける
- git flowとgithub flowとは？その違いは？
- https://speakerdeck.com/ken_c_lo/pull-request-4-designers-githubwoshi-tutapuroguramatodezainafalseitereteibunakai-fa-huro?slide=11
- 英語のコメントや issue で頻出する略語の意味 (FYI, AFAIK, ...)
ありがとうございます。
抜け漏れあったらごめんなさい。