00:05
はい、5月17日水曜日ですね。遅刻は9時7分になりました。 今日も、まあいい天気なので、暑くなりそうですね。はい、おはようございまーす。
memeのkeethこのくわはらです。では本日も朝活始めていきたいなと思います。 本日はですけども、前回と全然まだガラッと変わった内容なんですけど、
要はロジカルなコミットメッセージの書き方っていう記事をですね、読んでいこうと思ってます。 これあれですね、禅のトップに出てきたやつの一つで、
タイトル的に面白そうだったんで、読みたいなと思っていたんですけど、結局、昨日の夜読まなかったので、今から読んでいこうかなと思っています。
では早速行きましょうかね。プテラノンさんですね。おはようございます。ご参加いただきありがとうございます。 今日も今からタイトルの記事をダラダラと読んでいこうと思っております。
行きましょう。チーム開発におけるコミットメッセージの書き方についてアウトプットします。 コミットメッセージに正解はありません。組織によって最適な手法は異なるため、参考の一つにしてみてくださいと。
一応、初心者の方へという注意書きがありますが、何もわからないうちはおさほを守るよりも成長することの方が重要です。
成長するためにはおさほがんむしでいろいろ試したり、たくさん壁にぶつかり失敗することも必要です。 ただし重要なことは失敗から学ぶことであるため、必要な知識経験したことはしっかり吸収しましょう。
おおむね同意なんですけどもちろんチームであったりとか場によっておさほがんむしするとこいつ協調性ないなという評価になりかねないので、
がんがむしして失敗してそこから学ぶっていうのはすごく大賛成なんですけど、ケースバイケース場所を選んでいただけたらいいなと思ってます。
はい、余談でした。じゃあ続いていきましょう。要点ですね。要点としてはですね、フォーマットを決めようという話なんですけど、フォーマットとしては最初にコロン、絵文字、コロンで閉じといて、そこにタイトルで次にスラッシュしてリーズン、理由ですね。
で次にスペシフィケーションで最後にイシューですというような流れのフォーマットでコミットメッセージを書くっていうのがこの人の主張だそうです。
絵文字はもう単純に絵文字ですね。内容とか種類をとりあえず目で視覚的にわかるようにしたいというのが冒頭にきて、次のタイトルはもちろんタイトル、概要ですね。
で続いてリーズンですね。これはこのコミットする理由ですね。っていうのを次に書きます。でスペシフィケーションは言い訳ではなくてこのコミット内容になった意図とか仕様とかその辺ですね。
理由付けのところをお話し書きましょうと。なんかさっきのリーズンとスペシフィケーションは結構セットになっている感じはしますね。
どう切り分けるかは意外と難しい気がしますけど。ラストイシューですね。その対応するイシューの番号かなんかリンクか付けてくださいということですね。
作業内容はコードを見ればわかるので、概要とか変更理由とか、意図とか仕様というのを簡潔にまとめましょうということです。
例としてのコミットメッセージが2、3個くらい書いてますね。例えばセードリング、イニットリードミーとか、バグか、虫ですね。
で、アップダウンっていうのがタイトルで、マジック.cっていうのが、マジック.cのスワップフォー、マジック.cソートっていうような
03:06
概要ですね。とかだったりとか。色んなメッセージが出ています。基本的に区切りはこの人はスラッシュで書くらしいですね。
さっきのように、絵文字、スペース、タイトル、スラッシュ、リーズン、スラッシュ、スペシフィケーション、スラッシュ、イシューというような感じで、スラッシュ区切りでこの人は書くらしい。
コミットメッセージは、そもそもなんで書くの?っていう、書く理由なんですけども、そもそもコミットメッセージを書く理由というのは以下の通りです。
1目でどんなコミットなのかっていうのを判断するため。簡潔にコミット内容を説明するため。なぜこのコミットが必要なのかっていうのを説明するため。
イシューベースで開発を進めるため。コードレビューや不具合があった場合に原因追及を助けるため。
はい、まあ大体そんなところですね。逆にコミットメッセージに不要なものっていうのを定義していて、それは以下ですよと。細かすぎるもしくは大きすぎる処理の説明ですね。
まあそんなものはドックスドキュメントで書くべきですよと。あとは処理の内容ですね。コード見ればわかるんで、その内容をコミットメッセージに書く必要はないねと。
で、言いたいこともしくは助けてほしいことみたいなことを書くと。まあそれはそのメンバーにチャットして相談をしてください。最後言い訳とか独り言ですね。
これはマストドンでつぶやきましょうと。まあマストドンかプライベートなところで通したコミュニティでつぶやいてくださいと。
で続いて、本題のロジカルなコミットメッセージとはというお話ですけども、コミットメッセージにおいて重要なことっていうのはドックスにも書かれておらず、コードだけ見てもわからないみたいな内容をコミットの内容に簡潔に伝えることですよと。
で以上の内容を踏まえてコミットメッセージに含むべき項目っていうのは、まず一つ目の絵文字ですね。一面でどんなコミットなのかっていうのを判断したい。まあ確かにそれはコードで見てわかんないですからね。
で続いてタイトルですね。まあこれは当たり前ですけど、まあ内容を説明したいと。で、reasonですね。コミットの、なぜこのコミットが必要だったのかっていうのを説明。で、スペシフィケーションで、なぜこのコミットの内容になったのかを説明するため。はいはい。
大元がreasonで、それを具体的な内容になったですね。に帰着した理由とかを書きましょう。で最後、issueです。これはissueベースで開発を進めるためと。まあこのissueのところはですね、チケットをどこで管理するかですね。GitHub issueでやるチームもあれば、まあJiraとかNotionとかなんやらかんやらといっぱいあると思いますけど。まあどこでissueとかチケット管理するかを置いておいて、まあそれのあれですね、番号とかっていうのを付けるべきなんでしょうね。
で、一応コミットメッセージのフォーマットができましたと。さて具体的な状況を設定してコミットメッセージというのを書いていきましょう。絵文字ですね。一個一個今の説明をしていくらしいですけど、まずコミットの種類ですね。バグ改善なのか新機能実装なのかパフォーマンス向上なのかなどなどっていうものを一目で伝えるのが絵文字ですと。
で、Git文字っていうものがあるので、そこに既存の有益な記事があるためそちらも見てくださいと。Git文字っていうサイトがあるんですね。なるほどなるほど。はいはい、これいいですね。僕知りませんでした。あとはGitのコミットメッセージに絵文字を入れて社内の開発効率を上げた話とか、Git文字の使い方みたいないろんな記事のリンクがバーッと貼られてるんで、まあ興味ある人は見てみてください。
06:07
例えば新機能開発だったらニューフィーチャーズっていう絵文字があるのでその絵文字にしましょうとか、まあそんな感じですね。いろんなGit文字の絵文字が貼られてますね。バグだったらもちろんバグっていう虫のやつがあって、メモだったらメモとかがありますし、パフォーマンス改善のためにはロケットみたいな絵文字もあったりしますし、なんかいい感じのリリースだったり今回のマージで大きいリリースだったりするときはターターっていうのを付けましょうと。あのクラッカーのやつですね。
なおなおGit文字これすごく使いやすくて良さそうですね。
はいでは続いてタイトルですね。タイトルはもうまんまです。コミットの概要のお話ですね。いろんなやつを簡潔に一言でまとめたっていうものですね。タイトルでした。例えばですね今コミットを見てるんですけど、
issue4であるお問い合わせフォームを実装するためにforms.pyにクライアントフォームを作りお問い合わせフォームの実装を行いましたというところで、もしこういうコミットとかタイトルだった場合はタイトルはsetClientFormにしましょう。そんな感じですね。
では続いてなぜそのコミットを行うのかっていう理由の話ですけど、もちろん簡潔にコミットを行った理由について書くと。先ほどの同じタイトルですね。
issue4であるお問い合わせフォームを実装するためにforms.pyにクライアントフォームを作ってお問い合わせフォームの実装を行ったっていうのがあった場合に、なぜそれを行ったかっていうところの理由ですけど、今回の例だとお問い合わせフォームを実装する理由っていうのはお問い合わせ対応するためだっていうところで、reasonはforSupportClientにしましょうと。
うーん、なんかちょっと僕ここ違和感があった。言語ができないですけどなんとなく違和感があるreasonだな。
ここではですね、issue4が立てられた理由をreasonに使用していますけど、issueがある場合はreasonを省略。issue内で既に示されているため、そっちを省略してもかまいませんと言っています。
reasonを省略する場合もあるんです。その場合は、最後のissueのところがわかりやすくナンバーになっているからいいのか。
途中ですね、reasonって3つ目のところなので、3つ目のところを省略されると書かれているものがreasonなのかspecificationなのかわかりづらくないってちょっとissue思いましたけど。
理由が全部issueに書いてあるからissue番号だけでいっちゃいいかもしれないです。
では続いて、specificationの話ですね。
なぜそのコミット内容になったのかっていう意図とか主要を伝えますと。
ここで注意すべきことは絶対に言い訳を書かないことですよというところでした。
コード内のコメントにも言えることですけど、コメントで言い訳をするようなコメントとかコードを見ないと意味がわからないというコードはそもそも書くべきじゃないよと。
言い訳ですね。同様に言い訳をするようなコミット、もしくはコミットメッセージを見ないと意味がわからないコミットはそもそもするべきじゃない。
このspecificationはコミットメッセージにおいて重要な要素であるためロジカルに書いてくださいと。
先ほどの例のspecificationでいくとbyforms.clientformにしましょう。
ラストissueですね。これは開発手法などによって異なりますが、issueベースで開発を進めている場合はissue番号をコミットメッセージに組みます。
09:07
issue番号をコミットメッセージに書いた方が参照しやすく意図がわかりやすいコミットになります。
1つ書き忘れましたが、コミットメッセージにissue番号をつけているとGitHubでissueとコミットを紐付けることができます。
勝手に紐付けてリンクにしてくれるんですよね。
sharpナンボってつけておくと。
で、コミットメッセージからissueへ、issueからコミットメッセージへというリンクがつけられるので、ぜひぜひつけておいてくださいと。
そんな感じですね。
もちろんissueはissue-sharp-4みたいな今回の例ですね。
で、作っておくと。
で、完成したコミットメッセージですね。
改めてちょっと繰り返しになりますけど、今回のコミットの内容としては、
issue-sharp-4であるお問い合わせフォームを実装するためにforms.pyというファイルにクライアントフォームというクラスを作ってお問い合わせフォームの実装を行いましたという内容です。
それに対してのコミットメッセージは、まず絵文字はSparkleですね。新機能実装なんでSparkle。
で、セットクライアントフォームというのがまずタイトルです。
で、reasonはfor support client。
で、specificationですね。というのはbyforms.clientform。
で、最後にissueはissue-sharp-4という感じです。
英語になっているから余計そうなんですけど、直接的すぎて僕は逆に分かりづらくなっちゃったんだけど。
みなさん分かりやすいですかね。
あと、今僕音読しているからみなさんは余計に分かりづらいかもしれないですね。
ちょっと記事後でツイートしますのでみなさんは今度見てみてください。
ロジカルなことはすごく伝わってきますし、しっかりフォーマットされているのは分かったんですけど、
僕としてはなんか全然分かりづらくなっちゃったなという感じがしますね。
結局これどういうことをやったのっていう、その冒頭のやったことのあれですね。
仕様を読まなきゃ分からない気がしているので。
なんかコメントメッセージ長すぎるのはそれはそれでどうなのって気がするので、
僕としてはなんかreasonとspecificationをいい感じでマージして書いた方がいいかもしれないですね。
絵文字タイトルまでは分かります。で、issueも全然分かります。
reasonとspecificationがだいぶ似通った内容なので、僕はここが結構ごちゃってるなる気がしました。
でも実際ちゃんとやってないので分かんないですけどね。
はい。で、戻りました。逆に不十分なコミットメッセージの例ですけど、
例えばfixolonクライアントフォームとか、コミットメッセージお問い合わせフォームだけとかを書く、
そんなチームメイトはいや、それはダメでしょ。
あとフォームとかメッセージみたいなコミットメッセージが良くないメッセージですね。
docsにも書かれていないし、コードだけ見ても分からないようなコミット内容を簡潔に使えることっていうのができておらず、
いわゆるコミットの種類とか概要、理由、使用意図とかissueについて何も触れられていないというのが良くないというところですね。
はい。ここからは個人的な領域、一般論じゃなくて自分のお話になりますけれども、
まずエモジープレフィックスの種類についてのお話です。
使用するエモジープレフィックスの種類っていうのは各自カスタマイズすると良いと思っています。
実際にこの筆者の方が使っているプレフィックスっていうのは、
1、2、3、4、5、6、7、8、9、10、11、12個ありますね。結構ありますね。
まずはシードリング草のエモジですけど、これはイニシャルのために使うと。
12:00
今から生やすっていうところでイニシャルの意味をしています。
次にファイヤーですね。ファイヤーはアップデートフィーチャーズだそうです。
んー、なんか燃えてるからバグフィックス感はあるんだけど、そうなんですね。
アップデートフィーチャーズね。機能界のアップデートのところではファイヤーを使うと。
次にスパークルズですね。キラキラする星のやつですけど。
あれはニューフィーチャーズです。新しく機能実装したところはこっちを使う。
次はリサイクルエモジですね。リサイクルはリファクタリングを意味しています。
次はバグですね。虫のアイコンですけど。これはもちろんバグです。
次はアートですね。アートはいわゆるデザインのお話。多分スタイリングも含めているような気がしますね。
次はブックスですね。これはドキュメントです。そのまんまですね。
次はレンチです。工具のレンチのエモジですけど。これはコンフィギュレーションですね。
コンフィギュレーションは歯車の方が一般感がありますけど、この方々はレンチの方を使っているそうです。
次はザップですね。電気のザップのやつですけど。これはインプルーブですね。パフォーマンス改善とかの話かな。
続いてロケットのエモジですけど。これはパフォーマンスじゃなくてデプロイしたよっていうところのコミットメッセージにつけるエモジです。
次はDNAですね。まさにDNAなの。缶のエモジですけど。これはマージを意味すると。
マージのエモジDNAなのか。そうか。まあまあまあまあなんとも言えないところですけど。
だからこの辺は皆さんでカスタマイズしてくださいってことですね。最後はテストチューブっていうエモジがありますね。試験缶です。
試験缶ってテストチューブって英語で言うんだ。そのまんまですね。
逆にテストチューブを日本語に訳して試験缶になったんですね。今更知りました。
これはもちろんテストのコミットメッセージだという感じですね。結構確かに細かく分けると12個くらいになりますね。
そのアップデートフィーチャーズとニューフィーチャーズのところを分けているってところが結構きっちりされている会社さんとかチームなんだなって思いました。
はい。続いてコミットメッセージ用の拡張機能などについてですけど。
組織や開発手法によってシェルスクリプトや拡張機能等で統一する方が良いと思います。
多くのGit文字系拡張機能というのがありますけど、私はUIを曲折した結果普通にCLIで書いてますと。
まあまあそういう人もいると思いますね。
なんだかんだコミットって分からないですね。僕はCLIでやる派なんですけど、メンバーによってはエディターでやったりとかあれですね。
IDEの方のGUIでコミットする方っていらっしゃると思うので難しいですけど、僕はCLIの方でターミナルからコミットメッセージ書く派の人なので
CLIでコミットメッセージを勝手にフォーマッティングしてくれる方が楽やなと思いますね。
で、あとコミットメッセージの長さですけどもちろん長ければ長いっていう方が良い、などの話はありますけど、まあそれを良いと思う派閥も存在しますけど私はそう思いませんと。
なぜならコミットメッセージを書く理由はいかな通りだからですと。
えーと重複になりますけど、コミットメッセージにおいて重要なことはDocsにも書かれておらずコードだけ見ても分からないみたいなコミット内容を簡潔に伝えることですと。
15:04
これがコミットメッセージを書く理由ですから、長ければ長いって言うと簡潔じゃなくなるってところですね。
で、具体的にじゃあ何文字までっていう制限は別に設けてもないんですけど、まあ一行に収まる自然の長さっていうのを書いています。
まあそれ以上長いコミットメッセージになってしまう場合はDocsなどに書くべき内容だという風に考えています。
まあ確かに長すぎるってことは何かしらそのアプリとかシステムの仕様のお話が出てくると思うので、それはもう確かにどっかドキュメントでまとめておくのが良いと思いますね。
もしくはコミットメッセージにそれのリンクをつけてもいいかもしれないです。
いわゆるさっき言ったスペシフィケーションのところに理由これだみたいなところのリンクを貼ってあるのもいいかもしれないですね。
ただまあリンクを貼るとURLがガッと貼られるのでちょっと長すぎてコミットメッセージに長げーってなるかもしれないですけど。
はいでは続いて、あとコミットメッセージは日本語か英語が問題ですけど、私はコミットメッセージを英語で書いています。
グローバルなレポジトリにしたいから、語学力向上のため、英語の方がロジカルなコミットメッセージを書きやすいから、まあそれはそうなんだよね。
日本人しか扱うことがなく、メンバーも日本人だったらまさしく日本語で書いても構いませんけど、正直英語の方がかっこいいよねっていうのもあって。
まあそれもそうなんですよね、英語のコミットの方がかっこいいねは普通に共感しました。
あとこの記事を書くきっかけとか参考書籍のお話が貼られてますね。
Gitを使い始めた頃は雑なコミットメッセージばかり私も書いてたでよ。
初めての個人開発、Octo-2っていうのを作ってたらしいんですけど、その時のコミットメッセージのキャプチャーが貼られてますけど、確かにこれはひどい。
ファーストコミット、更新ボタン、文字数制限改良、デリート、DB.sqlite3、Gitignoreっていうのがコミットメッセージだったらしくて。
いやまあ想像はつきますけど、さすがにわからんって感じですね。
まあなんですけど、チーム開発でバックエンドを担当した時に自分の中ではわかりやすいコミットメッセージを書いたつもりが全く理解されませんでした。
その時に言われた先輩んちな一言がロジカルなコミットメッセージを書くように意識し始めたきっかけですと。
お前がわかるコミットメッセージはお前しかわからん。誰が見てもわかるコミットメッセージを書けという話を聞いたそうですね。
これはチーム内のコミュニケーションやマネジメントに通じることと思っていて重要なことは相手がわかるかどうかというところです。
わかりやすく書こうとここを開けるだけでなく、どうすればわかりやすくなるのか、そもそも何のためにやっているのか、
仕組み作りから改善できる問題ないのかというのを考えていくことが大切だと思います。
これ本当に良いメッセージですね。
参考として、良いコミットメッセージの共通点と書き方、便利なテンプレートやチーム開発時のおさほまで詳しく解説という別の記事のリンクも貼られていますね。
最後にですけど、綺麗なコミットを積み重ねてチヤホヤされましょう。
というところでこの記事は締められておりました。
ごめんなさい、あまりにも音読だったのでコミットメッセージを僕が音読してもわかりづらいし、
なんだかんだコミットメッセージで目で読むもんだなって今、僕はこの記事を見ながら改めて思いました。
なんですけど、フォーマットを決めておくことは本当にすごく大事なことで、
うちの場合はGoogle社のアンギュラJSの方ですね。
18:02
いわゆるアンギュラ1という言い方を俗には言いますけど、
アンギュラ1のディベロッパーズMDが出ますよね。
リードミーに書いてある。
そこに書いてあった僕はプレフィックスを使うようにしてますね、コミットメッセージ。
例えば、fixコロンとかdocsコロンとか、あと調和ですね。
開発環境周りの調和コロンとかっていうので、
冒頭のそのプレフィックスコロンのところで何をやってるかっていうのを示して、
その後にコミットメッセージを書くと。
で、リンクとかがあれば一番後ろにシャープなんちゃらっていうのを付ける。
もしくはもうイシュー番号とかでブランチ名に指定して切るっていうこともやったりしますかね。
まあいろんなやり方ありますけども。
コミットメッセージそのもので一個一個のメッセージのフォーマッティングをがっつりやるかというと、
そこまでやってはなくてですね、普通にプレフィックスしか付けてなかったので、
その中身のところですね、タイトルとそのreasonとディスプレイフィクションまでしっかり分けるっていうのを考えたことはなかったので、
一つ考えるきっかけいただいたとして僕はありがたいなと思いましたね。
この方はそれをそれぞれスラッシュ区切りでしっかり切って書くみたいなことですね。
っていうのをやってたらしくて。
まあそれは一つのやり方としていいのかと思いましたし、
確かに意外とプレフィックスさえ付けてしまえばまあええやろう感がなくはないので、
まあそこから先のもうちょっとメンバーに伝えるっていうところですね。
で、コミットメッセージをメンバーに伝えるっていうのはあれですけど、
未来の自分が読む時もこれこいつ何やったっけっていうのはやっぱり未来の自分で過去の自分は他人なので、
そういうことも含めてしっかりメッセージをフォーマットするっていうのは、
なんだかんだ他の人の時間を奪うっていうところを解消できるので、やっぱ考えていきたいと思いましたね。
こういうところがやっぱりエンジニアリングの細かなところの仕事、スキルの一つですよ。
はい、というところで、すいません余談ばっかりだったんですけど今日の朝勝は。
まあ30分も近づいたのでこの辺で区切ろうと思います。
はい、改めまして今日の参加者はSueさんとPteranodonさんですね。
はい、改めてご参加いただいてありがとうございました。
明日もですね、なんかゆるゆる記事読んでいきたいと思いますので興味あるら参加してみてください。
では、水曜日中日ですね。今日も一日頑張っていけたらなと思います。
それでは終了したいと思います。お疲れ様でした。
