00:04
はい、12月8日木曜日ですね。 四国朝9時。ちょっと10分もあってしまいました。
最近、朝に寝坊することが大変に多くてですね、 大申し訳ないです。はい。
おはようございます。ひめみのきーすかとくわはらです。 じゃあ、本日も朝活を始めていきたいとおもいます。
今日はですね、 技術の記事ではあるんですけど、ちょっと
開発というよりも、まあまあギットのお話かな。 まあコミットの話ですね。
はい、まずタイトルにある通り、The Perfect Commitというタイトルですけども、 まあそのコミットメッセージの何回、
吉橋みたいなところはあると思うんですけど、そのコミットメッセージに関するお話があるそうですね。
なんか、SHIMOっていう方が記事を書かれていて、その完璧なコミット。 まあその完璧の定義も結構難しい人。
まちまちだと思います。チームによってもどういうコミットがいいかっていうのは、 議論は分かれるところであると思うんですけど、
まあその別のコミットのところですね。 まあ参考にしていきたいなと思う気がするので、読んでみようと思いましたって感じですね。
いきます。The Perfect Commit。 ここ数年私は自分が考える完璧なコミットを作ることを中心に仕事を進めようとしています。
これは次のすべてを含む単一のコミットのことを意味します。 大きく4つありますが、1つ、実装ですね。
1つの焦点を絞った変更だと。 2つ目に、その実装がどうさせることを示すテストだと言っています。
3つ目に、変更を反映したドキュメントの更新ですね。 ラスト、より詳細なコンテキストを提供する課題スレッドへのリンクだと言っています。
それぞれについて一応太字になっているのが、実装、テスト、ドキュメンテーション、 イシュースレッドみたいなところです。
私たちソフトウェアエンジニアの仕事っていうのは一般にゼロから新しいソフトウェアを書くことではありません。 私たちは既存のソフトウェアの機能追加だったりバグフィックスに大半の時間を費やしていますよと。
コミットっていうのは私たちの仕事の主要の単位になります。 コミットは熟慮の上、慎重に扱われるに値しますと。
2022年の11月26日更新追記があって、 25分間の講演のリンクが貼られてますね。
マッシブリインクレースユアプロダクティビティオンパソナルプロジェクトウィズ コンプリヘンシブドキュメンテーションアンドオートメイティテスト
こういうタイトルの25分間の講演があって、 そこでソフトウェア開発へのこのアプローチについて詳しく説明してますよと。
これはご本人かな?
あると言えば興味のある方は見てみてくださいというところです。
ではそれぞれの4つの大事な項目について解説していきたいと思いますが、 まず一つ目ですね。インプリメンテーション実装の話です。
03:00
各コミットっていうのは一つのことを変更する必要があります。 ここでいうモノの定義っていうのは意図的に曖昧なままにあえてしておきますと。
目標は簡単にレビューができて、将来的にGitBlameとかGitBisectですね。
Bisectというのかな?これ未だに読み方はBisectかBisectかわかんないんですけど。 めったに使わないからあれですけどね。
まあいいや。のようなツールを使って、 裁縫した時に明確に理解できるようなものを持つことですと。
余談ですけど、GitBlameっていうコマンド僕はすごく実は苦手じゃない。苦手というか、 嫌いじゃないんですけどあんまり見たくないなっていうものがあって。
というのもだいたいGitBlame叩くと自分のコミットじゃんっていう経験がすごく多いので、 あんまGitBlame叩きたくないけど時には見ますね、やっぱり。
はい、という余談でした。 でも私はコミット履歴を直接的にする、直線的にするのが好きですと。
その方が後で理解しやすいからです。 そうすることで各コミットが単一の集中した変更であるという価値をさらに高めることができます。
Atomic Commitっていうコミットの方があるんですかね。 コミットっていうのは何かが問題が発生した時に簡単に元に戻せますし、
他のブランチにチェリーピックすることもできますと。 コミットをなるべく流度を小さくした時のことをAtomic Commitって言ってるんですね。
ウェブアプリケーションのように本番環境にデプロイできるものについては、 コミットはデプロイ可能な単位であるべきです。
メインブランチをデプロイ可能な状態に保つことが、コミットが賢明なアトミック変更であるかどうかを判断するための良い経験則となります。
なるほどでした。 ウェブアプリとネイティブアプリって、その変更容易性とデプロイの容易性の差が大きすぎるので、
特にウェブアプリケーションの場合はコミットの流度とか単位を小さくしておくのがすごく大事なことだと思いましたね。
まあ別にアプリの方もそうだとは思いますけど、 アプリはゆっくり審査を通して、そこからさらにビルドしてデプロイするみたいな、
1個でかいフローが挟まないといけないので、ここが大きな差ではありますよね。
まあでもどちらにしろ、コミットはなるべく小さくしておくのがすごく大事だと思いますね。
さっき言ってたコミット履歴を直線的にするのが好きっておっしゃっていたんですけど、
これだから、スカッシュ&マージもするのかどうかすごく気になりましたけどね。
一本にはなるんですけど、この辺、マージの、ギター部でマージって3つ?4つ?あったと思いますけど、あれの何を使っているかすごく気になりましたね。
はい、まあいいや。では続いていきましょう。今のが実装の話で、続いてテストの話ですね。
はい、ではテストについていきます。テストの究極の目標というのは、生産性を向上させることになります。
もしあなたのテストのやり方が遅くなっているのであれば、それを改善する方法を検討すべきです。
長期的に見ればこの生産性の向上というのは、変更を加える、自由を得ること、そしてその変更が他の何かを壊していないことを確信できるようになることから生まれます。
06:00
しかしテストは短期的にも生産性を向上させることができます。あなたが行った変更が完了し、コミットする準備ができたとき、あなたはどのようにそれを知ることができますでしょうかと。
新しいテストが合格したら事前準備は完了ですと。ああ、なるほどね。
そうすることで自分自身に対して二の足を踏んだり、エッジゲースを全て考え尽くしたかどうかというのを疑ったりする時間を減らすことができるんですと。
テストがなければあなたの変更が他の潜在的に無関係な機能を壊している可能性が非常に高くなりますと。
あなたのコミットは何時間もかかる退屈な手動テストによって妨げられるかもしれません。あるいはYOLをヨロしてしまい、後で何か重要なものを壊してしまったことを知ることになるかもしれません。
既に良いテストプラクティスを実装しているのであれば、テストを書くのにかかる時間もずっと短くなりますよと。
既存のテストがたくさんあるプロジェクトに新しいテストを追加するのは結構簡単です。
必要なパターンは90%が既に完成されている既存のテストを見つけることが多いからですよと言ってますね。
ということはこの人は多分テストカバレッジ90%ぐらいを大体基準にしているってことかな。
何十%にするかっていう基準はチームによってまちまちですけどね。僕は大体85%ぐらいにしてますよ。
お客さんからすると90%って言われるかもしれないですけど。
続けます。もしあなたのプロジェクトにテストが全くないのであれば、変更のためにテストを追加するのはもっと大変な作業になるでしょうねということです。
このような理由から私はすべてのプロジェクトで合格するテストから始めます。
テスト駆動に近い感じですね。このテストが何であるかは問題ではありませんと。
このテストっていうのがアサートでマイナス1とプラス1で
イコール2であると。これが正常であるよということですね。重要なのはテストフレームワークを用意してコマンド
私の場合は通常Pyテストですね。Pythonで書いてるのかこの人は。
Pyテストを使って実行してテストスイートを実行できるようにすることです。まあ別に何でもいいんですけど
コマンドで実行できるようにしておきましょう。そうすることで自動化ができたりとかいろんなところに流すことができる
私はほとんどすべての新しいプロジェクトにこのクッキーカッターっていうテンプレートを使ってるそうですね。
クッキーカッターというテンプレートがあるらしく。ちょっと見てみますと
ダイナミックコンテンツフォーギットアップリポジトリテンプレート ユーザングクッキーカッター&ギットアップアクションズっていう
同じ人の別の記事ですね。なるほど。自分で作ったものかな。わかんないですけど。
リンクはこの記事から飛ばれるのでもし興味あったら見てみてください。僕も見てみて興味あったら明日読むかなと思います。
このテンプレートを使って新しいプロジェクトにテストを追加します。このテンプレートっていうのはそのテストフレームワークを構成するためのものでテストに合格した単一のテストとギットアップアクションズのワークフローで最初からすべてを実行します。
私はテストファースト開発。コードを書く前にテストを書くことの第三者ではありません。
最終的なコミットでテストの実装を一緒にバンドルするテストコミ開発です。
09:05
みんながよくやるような実装テストのお話ですね。 テストに対する私のアプローチについてはPyTestとBlackというものを使ったユニットテストのごまかし方に詳しく書いています。
これも別の記事のリンクですね。PyTest&Black。Blackboxテストの話かな。
テストのノウハウというよりも基本的なマインド的なお話でしたね。
全プロジェクトテストを入れるというのはすごくいい話だなと思いました。 短期的に見ても生産性が向上するというのは全部のケースではないにしてもあるなと思いましたし、
テストないと影響範囲だったり他のソースコードを壊すことないかなというのは確かに気になるので、
やっぱりテストあると安心はしますよね。 次はドキュメンテーションの話ですね。
もしあなたのプロジェクトがあなたのプロジェクトの外で使われることを意図したAPIで定義しているのであれば、それらは文書化される必要があります。
私の仕事ではこのようなプロジェクトは通常次のうちの一つになります。 次のうちというのは大きく3つありますけど、1つはPython APIですね。
モジュールとか関数とかクラスみたいなPython APIですけど、他のプロジェクトにインポードされるように設計されたコードを提供するAPIですね。
続いてWeb APIです。通常最近はHTTP上のJSONだったり他のアプリケーションで消費される機能を提供するものです。
3つ目がClickとかタイパー、ARGPaaSというものがあるんですね。実装されているようなコマンドラインインタフェースのツールだそうです。
大きく3つ、これくらいのAPIがあるということです。
これらのドキュメントというのはコードそのものと同じリポジトリに置かなければならないですよというですね。それはそうでしょうね。
これはいくつかの理由ですごく重要です。ドキュメントというのは人々がそれを信頼する場合にのみ価値があります。
人々はそれが最新保たれていることを知っている場合にのみそれを信頼しますと。
ドキュメントがないとまず価値がないと思われて、それが最新保たれないとやっぱり信頼がないと。
上記の方の価値があるかどうかはちょっと難しい判断ですね。
まあ信頼できるかどうかというと確かに最新じゃなければやっぱり信頼できないですよね。
もしドキュメントがどこか別のウィキに住んでいるとしたら簡単に古くなってしまいますし、もっと重要なのはドキュメントがコードと同期して更新されているかどうか誰もすぐに確認することができないということですよね。
なのでドキュメントはバージョン管理されるべきです。人々は使っているソフトウェアの特定のバージョンのドキュメントを見つけることができる必要がありますと。
ドキュメントをコードと同じリポジトリに置くことで無料でバージョン管理を同期させることができますよと。
ドキュメントの変更というのはコードと同じ方法でレビューされるべきです。
同じリポジトリにあればコードのレビュープロセスの一環としてドキュメントに反映させるべき変更をキャッチすることもできます。
そして理想的にはドキュメントはテストされるべきですと。
へー、ドキュメントもテストするんですね。
私はドキュメントのユニットテストを使ってこれを行うアプローチについて書いてきました。
12:01
はい、これも別の記事のリンクを貼られてますね。
で、テストフレームワークを使ってドキュメントの中のサンプルコードを実装するのも良いアイディアです。
あーなるほどね、そういうことをテストするんですね。
私のコミットノークは1文字か2文字程度のドキュメントが含まれています。
これは書くのにそれほど時間は、1文字じゃないですね、1分か2分ですね、失礼。
これは書くのにそれほど時間はかかりませんけど、時間が経つにつれて非常にフォーカス的なものに積み重なっていきますよと。
エンドユーザー向けのドキュメントはどうでしょうかというところですが、これはまだ私自身が考えているところです。
スクリーンショットを最新の状態に保つプロセスを自動化するためにショットスクレーパーというツールを作りましたが、
エンドユーザー向けのドキュメントについてはまだ信頼の持てる習慣やスタイルが見つかっていないよということでした。
なるほどね。
またそのショットスクレーパーというスクリーンショットを撮るためのツールを自作したんですね。
はい、ということでした。
ドキュメント周りのお話でラストがリンクトゥアンイシューですね。
イシューのリンクのお話ですね。
さっきのドキュメントはコミットのお話とちょっと離れてる気がしますけど、
でもドキュメントそのものもテストするはちょっと僕やったことがないというか、
文章をテストするって考えたことがなかったので、なるほどねと思いましたね。
特に中に出てくるサンプルコードの動作検証をするというのはそれは確かにやると思いますけど、
その辺も多分この日は自動化してるんだろうなというので、
なるほど。
ドキュメンテーション・ユニット・テストという別のリンクがあるので、
これはこれでまた読んでみたくなりましたね。
ではラスト。
リンクトゥアンイシューですね。
課題へのリンクです。
完璧なコミットにはその変更に関連する課題すれというリンクが含まれていなければなりません。
コミットメッセージの中にそのリンクを入れろということですね。
これなかなか面白いですね。
プロディックの中に入れるならよくやりますけど、
コミットの中に入れるってなかなか面白いなと思いました。
時々コミットメッセージを書く数秒前に課題を開いて、
コミット自体からリンクできるようにすることもあります。
私が課題スレッドを好きな理由というのは、
その変更に関するコメントや背景を書くスペースが実質的に無制限になることです。
私の課題スレッドのほとんどは私が独り言を言っているようなもので、
時には何重もの課題コメントと一緒に全て私が書いています。
なるほど。
スレッドに書き込む内容というのは以下の通りです。
めっちゃいっぱいありますね。
1個ずつ読みますけど、1つ目は背景ですね。
変更の理由。私はこれを冒頭のコメントに含めるようにしています。
これも別にプロディックに書けばいいんじゃないかと思ったりしますが、
個人開発の話かな、背景としては。
個人開発の場合は、
確かにプロディックベースで個人開発しないからな。
その時は一緒にコメントを書いていって、
そのスレッドのリンクを貼るのは確かにありかもしれないです。
続いて、ステイトオブプレイなので、変更前の状態ですね。
現在のバージョンのコードやドキュメントにリンクすることが多いです。
これは数日後に未解決の問題に戻った時に、
15:01
最初の調査を繰り返さずに済むのでとても便利ですよということですね。
なるほど。
続いて、3つ目はLinks to Thingsですね。
物事へのリンクだそうです。
他のリンクがあるんですけど、
変更のインスピレーション、関連文書、
スラックやディスコードでの会話、
スタックオーバーフローで見つけた手がかりなどですね。
これは分かりやすいですね。
4つ目がコードスニペットですね。
潜在的な設計と誤差動を説明するためのコードスニペットです。
この人はPythonを使っているのでPythonの話ですけども、
Pythonなのに他の言語を使用したら一緒ですけど、
そんなものを使って書いていますよと。
ブロックを使ってコメント欄にシンタックスハイライトを表示させましょうと言っています。
続いて5つ目ですね。
5つ目は決定事項です。
何を検討したか、何を決定したのか、
プログラマーとして私たちは1日に何百もの小さな決断を実はしています。
何百もの小さな決断をしているってすごいですね。
そんなに皆さんしているのか。
それらを書き留めましょうと。
そうすれば将来、元の理由を忘れて、
それらを再吟味している自分に気づくことはないでしょうと言っています。
思想をコメントとして残すのはすごく大事なことなので、これは確かに賛成ですね。
続いてスクリーンショットですね。
スクリーンショットは前かどうだったか、後かどうだったかっていうのを視覚的に見るようにするということですね。
アニメーション付きのスクリーンショットであればなお良しですね。
私はLICE CAPを使ってGIF形式のスクリーンショットを作成して、
クイックタイムを使って動画をキャプチャーしています。
僕はクイックタイムを使って画面の動画を撮って、
何かのコマンドを使ってGIFに変換しています。
そういうのを変換してくれるシェルがあったので、
それをネットから見つけて、僕はそれを使っています。
ラスト、プロトタイプですね。
私はよくPythonのコンソールセッションからコピーした数行のコードを貼り付けます。
時にはHTMLやCSSを貼り付けたり、
UIプロトタイプのスクリーンショットを追加したりすることもあります。
それら以上のことを一周スレッドに書いていて、
そのスレッドのリンクをコミットに加えるということですね。
課題を閉じた後は、更新されたドキュメントへのリンクと、
理想的な新起動のライブデモへのコメントを最後に追加したいですね、
というのも言っています。
こんなことでした。
なかなかコミットメッセージにリンクを含めるというのが面白いなと思いましたね。
僕はやったことはなかったんですけど、
まだコミットメッセージURLってどうなんだろうって気はしますが、
別に変ではないので。
実は結構みなさんにもやってたんですよね。
僕は全然やったことないだけなので、
他のみなさんとかいろんな人がやってるんだったら、
いいプラクティスなんだろうなと思いますけど。
ちょっとこれらは漁ってみたくなりました。
今の4つがコミットメッセージで大事なことです。
そこからよりコミットメッセージのお話ですね。
具体的に入りますが、
コミットメッセージより一周の方が価値があるという話ですね。
私は数年間コミットメッセージにエッセイを書いて、
理解となる文脈や考え方をできるだけ多く取り込もうとした時期がありました。
18:03
コミットメッセージの中に更新したドキュメントをバンドルするようになってから、
私のコミットメッセージはかなり短くなりました。
これまでコミットメッセージに含めていた資料の多くが、
代わりにそのドキュメントに含まれていることがよくあるからですよね。
コミットメッセージを書く習慣を広げていくうちに、
コミットメッセージそのものよりも課題スレッドの方が、
この文脈の大部分にとって有利場所であることに気づきました。
スレッドは埋め込みメディアをサポートし、
より発見しやすく、コミットが完了した後も拡張しやすくし続けることができます。
今日、私のコミットメッセージの多くは、
一行の要約と課題へのリンクになっています。
長いコミットメッセージの最大の利点は、
リポジトリそのものと同じくらい長く存続することが保障されていることですよ。
もしここで説明したような方法で課題スレッドを使うのであれば、
長期的なアーカイブとしての価値を考慮することが非常に重要です。
これは議論を呼ぶと思います。
各リポジトリには、誰かがリポジトリをクローンしたときに
その全体がコピーされるような、完全で分散化された履歴の記録を読み込むべきだということですよ。
これは本当に議論があるでしょうね。
今のところの僕はちょっと欠言がありますけどね。
私はその哲学を理解しています。
私はここで言いたいのは、私自身の経験ではその要件を削除することで、
私の全体的な生産性が賞味で増加したということですね。
他の人は違う結論に出せるかもしれません。
もしこれがあまり気に食わないのであれば、
拡張コミットメッセージに背景情報だったり追加コンテキストを盛り込んで、
さらに完璧なコミットを構築することも一応歓迎はしています。
私がGitHub Issueを使って気に入っている理由の一つは、
包括的なAPIが用意されていて、
それらを使って全てのデータを抽出することができるからですと、
私はGitHub to Spriteというツールを使っていて、
自分の課題のコメントをSQLite Databaseファイルとして
原則的にアーカイブしています。
GitHub to SQLiteというツールがあるんですね。
それを使ってアーカイブをしているということでした。
コミットメッセージが長くなるというのは、
それはそれで僕はあまり経験したことがないですね。
なるべくコミットメッセージは短く、
コミットの流度とかどこまで変更したかを小さくすることはよくやりますけど、
メッセージ長くするのは実はそんなにしたことがないですね。
だいたいプルリクエストを投げたときに、
いろんな詳細だったりとか、観点だったりとか、
テストとかスクリーンショットとかっていうのを貼っ付けたりするので、
そこで他の人が見るようにしてたりするから、
あんまりやったことはないですけどね。
なんでそんなコミットメッセージが長くなったのかっていうのは気になりますね。
いろいろ情報を盛り込みたい話はなくはないですけど、
そんな情報量がたくさん込まれたコミットっていうのもどうなのっていう気は、
僕はちょっとしましたね。
ただ、このコミットがすごく重要な、コアな機能だったりして、
そこに対していろんな説明を確かに加えたりであれば、
そういうドキュメントリンクを貼るっていうのは、
いいかもしれないっていうのをちょっと感じました。
では続いて、
Not every commit needs to be perfect.
すべてのコミットが完璧である必要はないよっていう話ですね。
21:01
私の仕事の大半っていうのはこのパターンには果てはまりますが、
このパターンっていうのは完璧である必要はないよってことですね。
例外もありますと、
ドキュメントやコメントの誤字修正、誤字脱字の修正だったりとか、
そのままリリースすれば問題ありませんってことですね。
ドキュメンテーションに値しないバグフィックスだったりとか、
そういうものもですね。
それでも実装とテストをバンドルして問題へのリンクを貼りますけど、
ドキュメントを更新する必要というのは別にないですよと。
一般的には実装、テスト、ドキュメント、そして課題へのリンクっていうのを目指しますが、
私の仕事のほとんどすべてをカバーすることになると思います。
これは本当に良いデフォルトモデルですよって言ってますね。
単純な誤字脱字の修正ぐらいだったら、別にテストせずそのまま投げるって感じかな。
コミットメッセージを結構楽にするってことか。
テストは多分走らせるっぽいですね。
で、続いて、
Write scrappy commits in your branchですね。
ブランチでのスクラップコミットって言ってます。
探索的、もしくは実践的なコードを書いていると、
このような厳密な方法では意味がないこともよくありますと。
そのような場合、私は通常ブランチで作業します。
ここではwipのコミットメッセージだったりとか、
失敗したテストなどを自由に送信すればできますよと。
そしてそれらを一つの完璧なコミットにまとめて、
時にはGitHubのプレイケースで、
メインブランチを可能な限り整備することにしてますよってことでした。
ブランチ運用ルールも確かにすごく気になりますね。
この人はどうなんだろう。
あと最後ですね。
記事のリンクでいくつかのexampleが載ってますね。
exampleはコミットメッセージとissueのリンクの両方で書かれてますね。
例えば一つだけ開いてますけど、
コミットメッセージ、アップグレードドッカーイメージ
というPython3.11で、
クローズイーズ、シャープ1853というやつで
issueのリンクを。
そういう感じですね。
URLというか単純にシャープでやってるからか。
GitHubもあれですね。
コミットメッセージにシャープでちゃんとリンク貼るだけで、
そのissueへのリンクにブラウザ状態になってくれるんですね。
それはよくやるやり方か。
URLじゃないんですね。
そういうリンクを貼って、
やってることはシンプルに、
このコミットだと、
ドッカーイメージをとりあえず3.11に上げたよということですね。
ドッカーイメージのPythonを3.11に上げたよということです。
このissueをクローズしますよみたいな感じの書き方をすると。
分かりやすいですね、確かに。
これは良いプラクティスかもしれない。
これは確かに、
うちのチームでやってる人を何人か見ますね。
この1セットでずっとやっていってますよということですね。
以上、The Perfect Commitsというお話でした。
僕の予想してたのは、
コミットメッセージのフォーマットだったり、
プレフィックスをしっかりつけるとか、
その中の流度の話とかって、
そういう話だと思ったんですけど、
やり方としては、
issueリンクを貼って、
その中で思想だったり意見だったり、
自分が今まで意思決定した小さな細かいところとかのものを
ひたすらガーッと書いていくと。
そこのリンクをコミットメッセージに入れましょうということですね。
24:01
フォーマットはそんな感じで、
プレフィックスはこの人はその代わりにつけてない感じですね。
コミットメッセージを見る限りですけど。
僕はコミットメッセージにはやっぱり
プレフィックスつけてほしいなって感じはします。
あとはドキュメントそのものをテストするとか、
ちゃんとそれを同じリポジトリ内でバージョン管理しましょう
っていうのがすごく大事だというのは。
当たり前の話をちゃんと当たり前に定義してくれたという感じでしたね。
以上で、今日の朝活は終了したいなと思います。
参考になったら幸いですし、また明日。
明日は朝活できるかな?
ちょっと分からないですけど、
明日からですね、この日本を離れるので
朝からバタバタしている可能性があるので、
もしかしたらできないかもしれないです。
その時はご了承いただければ幸いです。
じゃあ、木曜日ですね。
今日も一日頑張っていけたらなと思います。
今日はだいちさんとねぶさんですね。
ご参加いただき大変にありがとうございました。
では、終了したいと思います。
お疲れ様です。
