開発でソースをいじっていると、何でここでこんな処理やってるの？ と言う場面がある。で、「こんな処理いらないから消しちゃえ！」とか言いつつ処理を変えたりして、本番デプロイしたら重大なバグが発生したとか。冗談ではなく世界中でこういうのが起こってると思う。
先日後輩がこんなことを言ってました。
おっしゃる通りで、コードが書かれた背景が分かると解決する場合が多い。解決しないまでもヒントには絶対になる。そうするためにはどうしてもコミットとチケットが紐付けられていないと厳しい。
しっかりした開発者であれば、チケットを作って、問題動作と期待動作を書いて、それに対してコミットを行うと言う一連の流れをきっちり行う。
しかし、イケてない開発者の場合。チケットも作らず、「バグ修正」と言うコメントとともにいきなりmasterブランチにコミットする(「bag syuusei」 と言うコメントの場合もある。てめーの頭がbugってる)。で、そいつが退職した後、別の開発者が「ここの処理クソだから直しちゃえ」と勇敢(明らかに蛮勇)にも処理を変更して、大バグを引き起こす。よくある。
目次
誰が悪いか？
ここで退職したイケてない開発者を「こいつクソじゃん」となじる。なじること自体は簡単だ。誰でもできる。1年目イキりエンジニアとかでもできる。
しかし僕は「こんなことできるようにしてるPLがクソ」と思う。gitとチケットの運用次第でこう言うことを防げるからだ。
ソースコードとチケットを紐つけ、ノウハウを確実に残すgit運用
僕が実践している方法を説明する。本業でも副業でも同じフローでやっている。これをやると、誰かがいきなり退職しても引き継ぎ問題が起こりづらくなる(真顔)。
以降githubを例に説明するが、bitbucketでもJIRAでもできる。 (RedmineやBacklogは知らない)
完成版
まず、僕のgithubのチケットを見ると分かりやすい。このサイトで使っているWordPressテーマのissueチケットだ。
このチケットを下に辿っていくと、
チケットに対して行ったコミットのリンクが紐ついている。無論これは僕が手作業で紐つけたわけではなく、コミット時にあることをやって自動で紐つけたものだ。
さらに重要なのが、
最後のこの部分。チケットをcloseするに至ったプルリクの情報が紐ついている。
このリンクをクリックし、
さらに「Merge pull request #13」と書かれた#13をクリックすると、
プルリクエストが表示される。実際にプルリクエストの内容を見ると分かるが、レビュアーによる指摘や、こうしてください的な指示が書かれているので、ソースコードがこうなった経緯が分かる。
またVisual Studio CodeにGitLensなどのExtensionを入れて該当のソースコード部分を見ると、
ソースコード上にチケット番号である「#10」が表示されるため、
と言う流れを作ることができる。
では具体的にやり方を説明する。
まずはチケットを作る
兎にも角にもチケットを作る。この時に、最低、タイトルにどう言う問題か、説明部分に問題点と期待動作だけ書いておけば何とかなる。スクショと軽い説明とかでも良い。万が一何も書かれていない場合どうにもならないが、そもそもそう言う状況を作らない運用にする。それは後述。
次にチケット番号を記載したトピックブランチを作る
チケットを作ったら、チケットの番号をメモしておく。下記の例だと
チケット番号は#10だ。なのでmasterブランチからチケット番号#10に関するトピックブランチを作って、そのブランチにcheckoutする。コマンドは下記。
トピックブランチ上で開発し、チケットと紐付けてコミットする
先ほど作った feature/#10 ブランチ上で、開発を行う。ローカルテストが終わったら、commitをしてリモートにpushする。その際に、コミットコメント上にチケット番号を記載すると、自動的にチケット上に表示されるようになる。
コミットする際のコメントは下記のような感じ。
とにかくチケット番号の#10さえ書かれていれば良い。こうすることで、
チケットとコミットが紐つくようになる。
ちなみにJIRAの場合だと、commitコメントに書かなくてもトピックブランチさえ作っておけば勝手に紐つく。JIRAすごい。
プルリクエストを作る
開発が終わったら、feature/#10 から masterへマージするプルリクエストを作る。
この時、タイトルにチケット番号を入れる。「チケット名」+「チケット番号」の書式が望ましい。この場合だと「記事一覧で一覧の高さが不定の場合に綺麗に横並びにならない #10」をタイトルにする。チケットへのリンクができる。便利。ただ、この時点ではチケット上にはプルリクのリンクはつかない。
ちなみにJIRAだとトピックブランチのプルリクを作っただけで、チケット上にプルリクのリンクが現れる。チケットを見ればすぐにプルリクが分かる。すごい。
マージコミットにチケット番号とチケットをcloseする旨を記述する
プルリクをマージする際に、マージコミットのコメントにチケットをcloseする旨を記述する。下記のような感じ。
「resolved チケット番号」と入れると、自動でチケットをcloseした上でチケットにコミットのリンク(=プルリクの情報)を残してくれる。
これで、チケットとソースの変更点(プルリク)、背景情報などがきちんと連携されたことになる。
本運用のメリット
これを徹底すると、例えば類似の改修があった場合、「あのプルリク参考にしながらやって」とか、指示することができる。チームに入って間もない人も、プルリクを参考に開発ができるので、早期にキャッチアップできるようになる。
またソースコードからいつでもチケットやプルリクに行けるため、背景不明の謎のコードが減る（なくなるとは言ってない）。さらにプルリクにテストの証跡などがリンクしてあれば、テスト証跡からリグレッションテストを行うこともできる。絶対に事故は減る。
とはいえイケてないエンジニアはこんなことやってくれないよ？ と言う方
「こう言う素敵な運用をしたとしてもmasterブランチに直コミットするバカが出てくるんだ。それに結構ややこしくてきちんとやってくれるかどうか疑問だな」と言う方、気持ちは分かる。
ただ、これもmasterマージできる人の権限を決めれば解決する話だ。
ご存知の通り、bitbucketでもgithubでもmasterブランチにマージできる人を絞ることができる。masterへマージできる人を特定の人だけにして、他の開発者はmasterマージできないと言う運用にすれば良い。
例えば、新しく入った人にはしばらくはmasterマージ権限を与えず、プルリクエスト時に各運用ができているかを既存メンバーがレビューする。チケットの記載がアレだったり(そもそもチケットを作ってなかったり)、きちんとチケットに紐つく運用ができていなければ、そこを指摘し直してもらう。場合によってはプルリクの却下もする。
masterマージしなければそいつの仕事は終わらないので、イケてない(と言われている)エンジニアも、イケてる方向に従わざるを得ない。(そうして段々とイケイケになり、最終的にイキりエンジニアになる)
こうすることで、イケてないエンジニアが謎コードを残して退職する、と言う最悪で頻出の事態を防ぐことができる。
そうして気づくはず。我々の運用もイケてなかったのだと。開発者個人の努力に依存して品質を高めようだなんてただのマネジメントの怠慢である。そう言う仕組みを作ることが重要だ。
まとめ
下記をすればちゃんとチケットとコミットを紐つけることができる。
- チケットを作る
- チケットに紐ついたトピックブランチを作る
- コミットコメントにチケット番号を入れる
- トピックブランチ→masterブランチのプルリクを作る
- プルリクのmasterマージ時にチケットをcloseするコメントをつける
ちなみに何度か出てきているJIRAの場合、1だけやってあとはプルリクをマージするだけで勝手にチケットに紐つく。良すぎ。JIRAは良すぎ。
お試しあれ。