きれいなcommit, pull requestを知りたい/作りたい方のためのgit勉強会

Slide 1

Slide 1 text

きれいなcommit, pull requestを知りたい/作りたい⽅のための git勉強会 @サポーターズCoLab ミクシィグループ株式会社Diverse 新規サービス事業部 Poiboyグループ今泉智博 (2018/03/27)

Slide 2

Slide 2 text

INDEX ⾃⼰紹介(3min) なぜ「きれい」なcommitを積むべきなのか(10min) きれいなcommitの原則(10min) きれいなcommitを作るテクニック (20min) きれいなPull Requestを作るテクニック(3min) 実際に⼿を動かして演習(10min) まとめとQ&A(4min)

Slide 3

Slide 3 text

自己紹介 ‣今泉智博: @imaizume ‣株式会社 in ‣ iOS版の開発を担当 ‣学⽣時代はWebフロント/Railsが主でした⏰ ‣昨年ラーメン120杯完⾷からの5kg減量達成 ‣2018年はCOMP⽣活と銭湯お遍路に挑戦中♨

Slide 4

Slide 4 text

Slide 5

Slide 5 text

突然ですが ❗

Slide 6

Slide 6 text

「きれい」って良いですよね

Slide 7

Slide 7 text

git のcommit logも「きれい」が良い✌ ということは

Slide 8

Slide 8 text

でもなぜ「きれい」であるべき❓ (なぜ「汚い」のはダメ❓) ❓

Slide 9

Slide 9 text

そもそもcommit logとは ❓ commit: 変更の塊の log: 履歴 002 001 003 + .green { + color: green; + } * 001: Committed at Jan 1st, 2018 | message: green classを追加 * 002: Committed at Feb 2nd, 2018…

Slide 10

Slide 10 text

変更には必ず「意図」がある ‣ Aという理由でプロパティBを追加 ‣ Cという不具合を直すためDを変更 ‣ 仕様EがFになったので不要なGを削除 commit: 変更の塊 commit に含まれる変更の「意図」が⾒えるべき

Slide 11

Slide 11 text

履歴は後から他⼈が⾒るもの ‣ 経緯不明の実装の犯⼈理由を探る時 ‣ 昔の実装を参考にしたい時 ‣ コードレビュー/PR作成時 log: 履歴変更の「意図」を正しく容易に伝えるべき

Slide 12

Slide 12 text

commit logの存在理由変更概要と意図を第三者に伝えるためきれいであるべき理由変更概要と意図を容易にかつ正確に第三者に伝えるため

Slide 13

Slide 13 text

♪ 個⼈のプロジェクトならきれいかどうかなんて関係ない❓

Slide 14

Slide 14 text

(試しに⾃分のcommit logを⾒返して何をしたか思い出してみよう) 「数ヶ⽉後のあなた」も「第三者」⚡ なんで⾃分はこんな実装したんだ… コメントは適当に “fix bugs”でいいか♪ 数ヶ⽉後

Slide 15

Slide 15 text

Slide 16

Slide 16 text

ところで「commitがきれい」とは❓ 「きれい」の価値観・判断基準は個⼈1⼈1⼈によって違うそこで今回は imaizume 独⾃の定義を使⽤

Slide 17

Slide 17 text

可読性 (readability) commit message の読みやすさ論理性 (logicality) 変更内容が意味的にまとまっているか「きれいなcommit」を構成する3要素 commitの粒度の⼩ささ原⼦性 (atomicity)

Slide 18

Slide 18 text

論理性(logicality) 原⼦性(atomicity) commit (ϝοηʔδ) commitྻ Pull Request ߦࠩ෼ ộ 可読性(readability) それぞれレイヤーが異なる Pull Requestの構成要素下の層での出来は上の層での出来に影響 ʴ (มߋ܈)

Slide 19

Slide 19 text

✨ 可読性 readability commit messageの読みやすさ

Slide 20

Slide 20 text

このcommit log を⾒て変更内容がイメージできますか❓ Project A Project B 2つのcommit logの差は何か❓

Slide 21

Slide 21 text

> fix width and height Project A の commit message ‣ 何のwidth/heightだろう❓(差分を⾒て分かれば良いが…) ‣ fixとは「固定」という意味❓それとも「修正」の意味❓ ‣ 何がどうダメだったんだろう❓(PRコメントもない…) > add / Update ‣ 何をadd/Updateしたんだろう❓ ‣ どうしてそうしたのだろう❓ ‣ػೳݟͨ໨తʹ͸Կ͕มΘͬͨͷͩΖ͏❓ commit messageからは変更概要が⾒えづらい

Slide 22

Slide 22 text

> Facebook登録時に学校情報がない時にデフォルト値を送信しない Project B の commit message ‣ おそらくAPIを叩く時のパラメータを変えたんだな ‣ でもなぜそんな仕様に❓ →PRコメントに仕様と関連issueへのリンクが記載 > 実際の職業を表示するセルのテキスト色を濃くする ‣ おそらく職業表⽰画⾯のUIの変更だな ‣ 理由は❓→PRコメントにデザインへのリンク commit messageから変更概要が⾒える

Slide 23

Slide 23 text

具体性のある内容を相⼿が理解できる⾔葉で書く読みやすいcommit messageを書くには

Slide 24

Slide 24 text

⚖ 原⼦性 atomicity commitの粒度の⼩ささ

Slide 25

Slide 25 text

ある⽇あなたは終業10分前に PRのコードレビューを依頼されました「よし、変更は1commitだけかすぐやっちゃえば定時で帰れそうだ✌」

Slide 26

Slide 26 text

☠ > File changed 1625 + 10671 - 9642 そして差分を⾒たあなた…

Slide 27

Slide 27 text

「うわあああああ」 YOU

Slide 28

Slide 28 text

「⽬が、⽬がーーー!!!」 YOU

Slide 29

Slide 29 text

☺ もし1commitの差分がこれくらいだったら❓

Slide 30

Slide 30 text

1つのcommit粒度をできるだけ⼩さくする⼩さな変更は⼀⾔で表現しやすい = 具体的なcommit messageも書きやすくなる注⽬箇所を集中、変更把握を容易にするには

Slide 31

Slide 31 text

⚙ 論理性 logicality 変更内容が意味的にまとまっているか

Slide 32

Slide 32 text

(あるWebフロントエンドプロジェクトにて) 「以前変更したヘッダーのメニューアイテムの並び順を変更前の順序に戻したいなぁ」そこでgit revert しようと commit logを調べてみると…

Slide 33

Slide 33 text

imaizume@mac ~/works/project (master) $ git log —oneline —graph -1 * 001 - (HEAD -> master) Update order and theme of header nav アイテムの順序変更とテーマ更新が同じcommitに含まれている commitをrevertするとアイテムの順序だけなくテーマまで戻ってしまうではどうすればよかったか❓

Slide 34

Slide 34 text

原⼦性を上げてみる imaizume@mac ~/works/project (master) $ git log —oneline —graph -4 * 004 - (HEAD -> master) Reorder header nav item in HTML * 003 - Add class switch with jQuery for header navigation to JavaScript * 002 - Add class for header navigation to CSS * 001 - Add section for header navigation to HTML 各ファイルでの変更をそれぞれ別のcommitに当初の⽬的は達成されたようだが… テーマを戻したくなったら 3 commit分のrevertが必要「不適切に」原⼦性が⾼い

Slide 35

Slide 35 text

✨ 意味的にまとまる範囲で原⼦性を向上 imaizume@mac ~/works/project (master) $ git log —oneline —graph -4 * 004 - (HEAD -> master) Reorder header nav item in HTML * 003 - Update header navigation themes * 002 - Enable SP header button appending new selector to HTML and JS * 001 - Use background-image on div instead of img element 意味的にまとまる範囲で commitへまとめた⼩さなcommitを意識しつつ、意味的にまとまっていると戻す時もまとめて戻せる「ファイルの粒度」ではなく「意味の粒度」にまとめる

Slide 36

Slide 36 text

commitの粒度は意味的にまとまる範囲で⼩さくする「これを戻したらあれも戻ってしまう」「これを戻すにはあれも戻さないと」は悪いcommitの可能性あり

Slide 37

Slide 37 text

‣可読性: 変更概要を簡単に把握できるようにする ‣原⼦性: 変更の粒度を不必要に上げない ‣論理性: 変更は意味的にまとめてcommitにする⼩まとめ: 「きれい」の定義と⽬的⽬的: 変更の内容と意図を他⼈=未来の⾃分に伝えるため

Slide 38

Slide 38 text

Slide 39

Slide 39 text

可読性 (readability) commit message の読みやすさ論理性 (logicality) 変更内容が意味的にまとまっているか再掲:「きれいなcommit」の構成要素 commitの粒度の⼩ささ原⼦性 (atomicity)

Slide 40

Slide 40 text

可読性 readability 変更概要を伝えやすい commit messageの書き⽅

Slide 41

Slide 41 text

commit ＝パッケージ化された変更 ➕ commit message = パッケージについたラベルパッケージの中⾝がひと⽬で把握でき想像できるメッセージに

Slide 42

Slide 42 text

どうすればひと⽬で変更を把握しやすいか❓ 1. 具体性再びimaizumeの独⾃定義 2. ⼈間的意味

Slide 43

Slide 43 text

具体性がないメッセージ例 ‣ Fix bugs ‣ Add new class ‣ 直した ⭕具体性があるメッセージ例 ‣ ヘッダーナビゲーションのボタンタップが正しく反応するようjQueryのセレクタ名を修正 ‣ WebViewへのリンクを可変にするため HogeViewControllerのコンストラクタにURLパラメータを追加 5W1Hで指⽰語や曖昧な⾔葉を使わない

Slide 44

Slide 44 text

⼈間的意味のないメッセージ例 ‣ addParamsメソッドの引数を0からに1変更 ‣ OLD_CONST1, OLD_CONST2を削除 ‣ MemberModelにsuccessフィールドを追加 ⭕⼈間的意味のあるメッセージ例 ‣ addParamsに間違った引数(0)が渡されていたので正しい状態値(1)を渡すように修正 ‣ ver2.0で廃止した登録関連の古い定数を削除 ‣ API取得が正常に完了したかを保持できるよう MemberModelに新規のフィールドを追加変更の詳細は差分を⾒れば分かるので⼈間的な意味を書くようにする

Slide 45

Slide 45 text

+ let tmp = Foo.bar(baz: Qux.quux) + let httpReq = + APIManger.getRequest(of: Endpoint.member) →コメントで補⾜が必要差分を⾒れば⼗分意図が伝わる過度にmessageの具体性を上げる必要なし補⾜1 ⼩さい差分で叙述的なコードならコードがcommit message として機能する場合も (参考: リーダブルコード)

Slide 46

Slide 46 text

補⾜2 チーム内での共通認識があればコンテキストは省略可能例:「アプリの設計はMVP」という⽅針 ⭕ XXXViewControllerの状態変数をPresenterに移設例: メンバ変数呼出しではselfやthisを明⽰的に付ける ⭕ YYYPresenter内のメンバ変数をself付きで呼び出し例: プロジェクト固有の概念や⾔葉がある ⭕ SuperMatchのspecial parameterを2倍にする

Slide 47

Slide 47 text

その他気をつけると良い点 ‣ 詳細な伝達事項がある場合 (ほとんどない) ‣ imaizumeは、基本的に1 line messageで派 GitHubやRedmineなどのIssue番号を⼊れる ‣ GitHub上でissueからもコミットが参照できる ‣ 「詳細はISSUEを⾒て」というメッセージに ‣ closeなどのキーワードでISSUEを操作可能 ✍必要なら複数⾏書く

Slide 48

Slide 48 text

✨ 原⼦性 atomicity 適切な変更量のcommitを作る⽅法

Slide 49

Slide 49 text

前述の例のようにならないよう 1commitの変更量を⼩さくする

Slide 50

Slide 50 text

みなさんはgit addする時どんなコマンドを叩いていますか imaizume@mac ~/works/pretty-git (master) $ git status On branch master Changes not staged for commit: (use "git add ..." to update what will be committed) (use "git checkout -- ..." to discard changes in working directory) modified: index.html modified: script.js modified: style.css no changes added to commit (use "git add" and/or "git commit -a") imaizume@mac ~/works/pretty-git (master) $ git add index.html git addの最小単位はファイルだと思っていませんか??

Slide 51

Slide 51 text

原⼦性の⾼いcommitを作るテクニック git add -p (—patch)

Slide 52

Slide 52 text

git addの最⼩単位は1⾏ファイル内の変更を⾏単位でstagingへ static var f… +func xyz() {… … -class Abc() {… - } +class Xyz() {… +} … -static let PQ =… git add -p git add 001 002 003 全差分をstagingへ差分を区間(hunk)毎に stagingへ 001

Slide 53

Slide 53 text

imaizume@mac ~/dots (master) $ git add -p diff --git a/notfy/Cell/NotificationsTableViewCell.swift b/notfy/Cell/ NotificationsTableViewCell.swift index 813e59f..b50e7ef 100644 --- a/notfy/Cell/NotificationsTableViewCell.swift +++ b/notfy/Cell/NotificationsTableViewCell.swift @@ -49,6 +49,7 @@ struct Notification { var memo: String } +protocol TriggerContract { + func toString() -> String +} extension Notification: TriggerContract { Stage this hunk [y,n,q,a,d,/,j,J,g,e,?]? git add -p 後の画⾯各hunkでの操作を聞かれるれるのでそれぞれで必要なコマンドを実⾏ ( ? でヘルプを表⽰)

Slide 54

Slide 54 text

add -p の各コマンド説明 (y/n) +hunk1 … +hunk2 … -hunk3 y: hunkをstageする y n: hunkをstageしない +hunk1 … +hunk2 … -hunk3 n ‣hunk1のstage確定 ‣h2へ移動 ‣hunk1の⾮stage確定 ‣h2へ移動 commit対象に含む commit対象に含まない

Slide 55

Slide 55 text

add -p の各コマンド説明 (q/a) +hunk1 … +hunk2 … -hunk3 q: 以降のhunkへの操作をキャンセル q a: 以降の全hunkをステージングにadd +hunk1 … +hunk2 … -hunk3 a ‣hunk1以降の全hunk の⾮stageが確定 ‣コマンド終了 ‣hunk1以降の全hunk のstageが確定 ‣コマンド終了

Slide 56

Slide 56 text

add -p の各コマンド説明 (j/J/k/K) +hunk1 … +hunk2 … -hunk3 k: 現在のhunkをSKIP 前の未確定hunkへ K: 現在のhunkをSKIP 前の⾮stage hunkへ +hunk1 … +hunk2 … -hunk3 ‣hunk3は保留 ‣hunk2はSKIP ‣hunk1に移動 ‣hunk3は保留 ‣hunk2に移動 (再度stageを選択可) hunk2は非stage確定済 hunk2は非stage確定済 k K

Slide 57

Slide 57 text

s: 現在のhunkをさらに⼩さく分割 (できる場合)

きれいなcommit logを積む

可読性

原子性

論理性

</body> Stage this hunk [y,n,q,a,d,/,s,e,?]? s Split into 3 hunks. @@ -8,4 +8,5 @@ <body> <div id="main" class="main"> <h1>きれいなcommit logを積む</h1> + <h2>可読性</h2> <div class="circle"></div> Stage this hunk [y,n,q,a,d,/,j,J,g,e,?]? 自動判定されたhunkは1個 3個の小hunkへ add -p の各コマンド説明 (s) ※hunkと⾃動判定されるには⼀定の⾏数以上の空き(未変更⾏)が必要

Slide 58

Slide 58 text

e: ⼿動でhunkを編集する

きれいなcommit logを積む

可読性

原子性

論理性

Stage this hunk [y,n,q,a,d,/,e,?]? e 連続した行に差分がある add -p の各コマンド説明 (e) 1 # Manual hunk edit mode -- see bottom for a quick guide. 2 @@ -8,6 +8,9 @@ 3 4

きれいなcommit logを積む

6 +

可読性

9 10 # --- 不要な追加差分は削除不要な削除差分は行頭を空白に viが起動

Slide 59

Slide 59 text

素のgitでhunkを操作するのは正直⾯倒くさい… (でもGUIツールではできない…)

Slide 60

Slide 60 text

tig で簡単にgit add -p addとcommitが j/k/u/1/Enter のみで完結

Slide 61

Slide 61 text

✨ 論理性 logicality 意味がまとまった commitを作る⽅法

Slide 62

Slide 62 text

✨ 意味的にまとまった変更をcommitにしよう imaizume@mac ~/works/project (master) $ git log —oneline —graph -4 * 004 - (HEAD -> master) Reorder header nav item in HTML * 003 - Update header navigation themes * 002 - Enable SP header button appending new selector to HTML and JS * 001 - Use background-image on div instead of img element ❌複数の意味を持つ変更を1commitに 1⾏/ファイル毎に変更を1commitに ⭕ 意味の最⼩粒度で1commitに頑張りましょう

Slide 63

Slide 63 text

‣とりあえずcommitしておきたい… ‣試⾏錯誤でTRY&DELETEを繰り返した… ‣commit messageを後で書き換えたい… というわけにはいかない commit logを再編集できれば… HTML <> CSS .{} JS $() 001 HTML <> CSS .{} JS $() 001 002 003

Slide 64

Slide 64 text

論理性の⾼いcommitを作るテクニック git rebase -i (—interactive)

Slide 65

Slide 65 text

rebase -i で commit log を再編集 =結合/分割/書き換え/順序⼊れ替えが可能 001 002 003 004 001* 002* 005 > Fix bugs > Remove methods 001* 002A 002B 005* 書き換え結合分割順序⼊れ替え

Slide 66

Slide 66 text

補⾜: rebase コマンドとは❓ →分岐元からの差分をfast-fowardでマージ master 002 dev 004 003 001 これを「対話的」に⾏うのが -i オプション 002 dev 004 003 001 master > git rebase master

Slide 67

Slide 67 text

imaizume@mac ~/dots (master) $ git rebase -i HEAD~2 pick e263636 vimにJqコマンドを追加 pick 2b9c492 write !pbcopyとsortコマンドのキーマップを追加 # Rebase 59d63fc..2b9c492 onto 59d63fc (2 commands) # # Commands: # p, pick = use commit # r, reword = use commit, but edit the commit message # e, edit = use commit, but stop for amending # s, squash = use commit, but meld into previous commit # f, fixup = like "squash", but discard this commit's log message # x, exec = run command (the rest of the line) using shell # d, drop = remove commit # # These lines can be re-ordered; they are executed from top to bottom. # # If you remove a line here THAT COMMIT WILL BE LOST. # # However, if you remove everything, the rebase will be aborted. # # Note that empty commits are commented out git rebase -i での画面説明どのcommitまで遡るか vimが起動するので⾏頭の単語と順序を編集後保存して閉じる各サブコマンド

Slide 68

Slide 68 text

rebase -i の各コマンド説明 (pick/reword/drop/順序入れ替え) pick: 何もしない (commitを残す) reword: commit messageを書き換え 001 001 001* > Fix bugs > Remove methods drop: commitを削除 001 (commitの順序⼊れ替え) 001 002 001* 002*

Slide 69

Slide 69 text

rebase -i の各コマンド説明 (squash/edit) squash: 直前のcommitと結合 edit: HEADを移動した状態で rebaseを⼀時停⽌ 001 002 003 001 002 003 HEAD 001 002 003 HEAD master master (detached HEAD状態)

Slide 70

Slide 70 text

editコマンドでのcommitの分割方法 001 002 003 HEAD 001 002 003 HEAD master master 分割したい 001 002 003 HEAD master 002の差分が未commit状態に 001 002B 003* HEAD master 002A rebase -i 001 && (edit 002) reset HEAD~1 add -p && rebase —continue addとcommitをやり直し可能!

Slide 71

Slide 71 text

補⾜変更されたcommitはhashが変わる⚠ =リモートリポジトリにPush済みのcommitを rebase -i した場合Conﬂictが起きます 001 002 003 master origin/master rebase 前 001 002 003 001 002 003 master origin/master rebase 後 001 002* 003* (⾃⼰責任でforce push OR 別ブランチでPUSH)

Slide 72

Slide 72 text

補足: git alias (ショートカット) rbi3みたいなaliasを設定しておくと便利

Slide 73

Slide 73 text

まとめ: imaizumeオススメのcommit作成⼿順 ProfileVC.swift 極⼒その場でadd -p&commit messageは最低限の質で Old Service Update VC/Service Update Add new property New Service Update Update TestClass プロフィール画面を作成〜ができるようYYYServiceを〜に変更〜ができるようYYYVCを〜に変更 OldServiceの一部をNewServiceに分離 ZZZAPIを管理するNewServiceを作成〜ができるようXXXClassの〜を変更あとでまとめてrebase -i 整理整頓後リモートPUSH ProfileVC.storyboard

Slide 74

Slide 74 text

Slide 75

Slide 75 text

きれいな Pull Request を作るには❓ 各commitだけではなく Pull Request全体も俯瞰する ‣ commit log を読み返してやったことを思い出せるか ‣ 順序やcommit粒度は適切か ‣ トータルのcommit数や差分が⼤きすぎないか ‣ Pull Requestのコメントは適切か

Slide 76

Slide 76 text

良いcommitやPRの先にあるもの commitྻ Pull Request ߦࠩ෼ ộ commit (มߋ܈+ίϝϯτ) ίʔυ Issue খλεΫ େλεΫ ϓϩδΣΫτ Ϗδϣϯ αʔϏε 良いコードが書ける良いcommitが積める良いPRが作れる良いISSUEが⽴てられる良いタスクの分割ができる良い仕事ができる‼

Slide 77

Slide 77 text

Slide 78

Slide 78 text

(時間があれば) 演習コーナー

Slide 79

Slide 79 text

Slide 80

Slide 80 text

git commitは「習慣」です⼼が変われば態度が変わる。態度が変われば⾏動が変わる。⾏動が変われば習慣が変わる。習慣が変われば⼈格が変わる。⼈格が変われば運命が変わる。運命が変われば⼈⽣が変わる。 (ヒンズー教の教えより) 良いcommitを習慣にしましょう (悪い習慣は変えましょう)

Slide 81

Slide 81 text

‣可読性: 変更概要を簡単に把握できるようにする ‣原⼦性: 変更の粒度を不必要に上げない ‣論理性: 変更は意味的にまとめてcommitにするまとめきれいにする⽬的: 他⼈=未来の⾃分に変更の内容と意図を正しく容易に伝えるため imaizumeオススメのcommit作成⼿順極⼒その場でadd -p&commit、messageは最低限の質であとでまとめてrebase -i して整理整頓

Slide 82

Slide 82 text

Q&Aコーナー(とありそうな質問) Q. 今⽇のやり⽅を常⽇頃から守らないとですよね❓ A. これはimaizume⼀個⼈の考え⽅・やり⽅、⽬的を⾒失なわぬように。⾒返す必要のないcommitを無駄にきれいにする必要はありません。 Q. 正直commit messageを考える余裕がありません… A. ローンチ時やリリース優先時等はやむを得ないでしょう。しかしメッセージを考える余裕もない状態が⽇常的に続くなら転職をお薦めします。 Q. commit messageは英語にすべきですか❓ A. 基本的には⽇本語の⽅が正確に意図の伝達ができ把握もしやすいので、⽀障がなければ⽇本語を推奨します。commit messageを読むの誰で、何のために書くのかを考えて選びましょう。

Slide 83

Slide 83 text

参考記事/リンク ‣ 横着で神経質な私とあなたに贈るgit add -p:  https://qiita.com/crifff/items/1abf08bca4ce51db4775 ‣ gitのコミットの歴史を改変する(git rebase) 1 / 2 · けんごのお屋敷:  http://tkengo.github.io/blog/2013/05/16/git-rebase-reference/ ‣ detached HEADを理解して脱Git初⼼者を⽬指す⽅のためのGit⼊⾨勉強会:  https://supporterzcolab.com/event/264/ ‣ Git - リベース:  https://git-scm.com/book/ja/v1/Git-のブランチ機能-リベース ‣ jonas/tig: https://github.com/jonas/tig ‣ peco と alias -g で git に便利⾰命おきた:  https://qiita.com/Kuniwak/items/b711d6c3e402dfd9356b ‣ Pro Git: https://git-scm.com/book/ja/v2

Slide 84

Slide 84 text

No content