コミット履歴を使用して、開発者に重要な情報を伝える必要がありますか？

最新バージョンからのサードパーティSDKのロールバックに関する会議で、開発者がコミット履歴で最新バージョンを使用すべきではないというフラグをすでに立てていることが確認されました。

一部の開発者は、これは悪い習慣であり、代わりにソースファイル（つまり// Don't upgrade SDK Version x.y.z, see ticket 1234）またはプロジェクトレベルのREADMEファイルのいずれかに記載する必要があると主張しました。他の人は、コミット履歴はプロジェクトのドキュメントの一部であるため、私たち全員がとにかくそれを読んでいるはずなので、そのような情報の許容できる場所であると主張しました。

重要な情報を他の開発者に伝えるためにコミット履歴を使用する必要がありますか、またはそのような情報をプロジェクトREADMEや関連するソースファイルのコメントなどの別の場所に複製する必要がありますか？

サードパーティSDKの新しいバージョンへのアップグレードを検討する場合、最後に見るのはソース管理システムの歴史です。

製品がSDKバージョン2.0を使用していて、誰かが3.0にアップグレードすることに興味がある場合、ソース管理システムで時間をさかのぼって、それが良いアイデアではないと判断するのは合理的ではないと思います。

ここには、すべての開発者が読む興味深い情報（コーディング規則、製品を構築するための開発環境のセットアップ方法、インストールする必要のあるサードパーティのものなど）を含む少数のページがあるチームWikiがあります。これは、サードパーティのライブラリのアップグレードに対する警告に適した場所です。

コミット履歴に注意する必要がありますが、通知を配置するのに絶対的に最適な場所は、依存関係を定義するのと同じ場所です。たとえば、アーティファクトの依存関係を宣言するmaven .pomファイルがある場合、次のようにします。

<!-- Do not change the SDK version because it causes Foo crashes. For more detail see Issue #123 -->

<dependency>線のすぐ上。

問題＃123には、クラッシュの詳細、クラッシュの原因となった更新バージョンの詳細が含まれます。おそらく、後で再検討するためにバックログに再度追加する必要があります。問題を修正するさらに新しいバージョンが存在する可能性があります。チケットを編集することで自動的に、または自分で手動で、現在の問題についてチームにメールで知らせ、現在トラッカーにいることで、後で再び見つけられるようにします。

依存関係宣言でそれを置く理由は、バージョンを変更したい人は誰でも、それを変更したい瞬間にそれを見て、なぜそうしないべきかを理解するからです。

誰かが依存関係のチェックを実行し、アップグレードを開始する状況を簡単に想像できるので、ソースコードにはコメントしません。そのために、TODOコメントごとにコードベースを精査する必要はありません。

問題チケットにリンクすることで、好奇心developer盛な開発者は失敗したチケットを知り、後で再訪する可能性があります。これがないと、かなり静的になり、再び更新されることはありません。

重要で直感的でない情報は、情報を検討するときに人々が見る場所に文書化する必要があります。

私が取り組んできたチームとプロジェクトについては、新しいバージョンが失敗した理由についてのコメントでロールバックをコミットします。新しいバージョンが修正されたら、バックログストーリーを追加してアップグレードを再試行します。ライブラリがリンクされているビルドシステム/ビルドスクリプトにコメントを追加します。

ロールバックは、プロジェクトの歴史を調べる際に、将来の開発者にコンテキストを提供します。バックログストーリーは、プロジェクトのアクティブな部分としてこのアップグレードの必要性を保持しています。ビルドシステムのコメントは、ライブラリが最終的に更新されるときに変更が必要な場所に適切です。

コードでコメントしたり、READMEに追加したりしません。アップグレードを試みることを考えている開発者は、これらの部分を見ていません。そこに追加した場合、ライブラリの問題が最終的に修正され、アップグレードが完了したら、それを削除する必要があります。多くの場合、この手順は忘れられます。その結果、プロジェクトの生産性を低下させるノートが作成されます。

プロジェクトのセットアップまたはフローが異なる場合、答えは異なる場合があります。重要なのは、開発者がアップグレードの作業を行う際に情報を正しく表示できるようにすることです。こうすることで、アップグレードの時期が適切でない場合、開発者はそれを確認して停止し、適切な時期に開発者はそれを確認してメモを削除し、将来の開発者を混乱させないようにします。

私は、マシューの重要な考えを答えで強調することで、マシューのコメントをもっと注目したかったのです。SDKをアップグレードしたくない理由があり、その理由は単体テストで把握する必要があります。リビジョン番号のチェックではなく、実際の根本的な理由。

たとえば、新しいバージョンにバグがあるとしましょう。そのバグをチェックする単体テストを作成します。後でSDKでそのバグを修正した場合、アップグレードはスムーズに行われます。互換性のないAPIの変更がある場合は、コードが新しいAPIをサポートするか、SDKが古いAPIをサポートするかを確認するテストを記述します。それは単体テストというよりも統合テストのようなものですが、それでも実行可能でなければなりません。

私の会社は1日に50件以上のコミットを生成していますが、私たちはそれほど大きくありません。すべての開発者がすべてのコミットメッセージを読んだとしても、率直に言ってしまわなくても、コミット履歴を記録する必要があるのは、人々がそれを思い出せないからです。そして、問題がない限り、人々は戻って履歴を読むことはありません。そして、彼らは、彼らが知っている限りではまだ起こっていないというアップグレードの問題を疑う理由はありません。

短期的には作業の重複を防ぐために必ずメールを送信し、ビルドスクリプトとREADMEまたは正誤表に書き留めてください。ただし、特に新しいバージョンの問題が微妙でトラブルシューティングに時間がかかる場合は、それを明らかにする方法が必要です。それは単体テストを意味します。

「コミットメッセージを介してのみ、他のチームに発見した重要な情報を伝えるべきですか？」と質問を書き直しています。私はそれがいいえ、それはあなたがすべきではないことを明らかにするためだと思うので。私は多くのことを伝えようと努力しています（私の経験では、これはほとんどの開発チームが積極的に努力する必要があるものです）。

そのような発見につながる一連のアクションがチケットによってトリガーされた場合、チケットを更新し（これを知っている必要がある人々が可視性を持っていることを確認します）、私はおそらくそれを対面で言及します少なくとも誰かに「おお、デイモンがそれを更新することについて何か言ったと思う」というしつこい感覚を残すために）、そしてもちろん誰も更新できないようにSDKが含まれた時点でコードにコメントを残したいそれを見る機会がなくても。開発ウィキのどこかでジャムできるかどうかもわかるかもしれませんが、それは現在のチームではなく、将来の雇用に目を向けてより多くのことを行っています。

問題に遭遇して発見するのにおそらくかかった時間と比較して、ほんの数分しかかかりません。確かに、私たちのドキュメントの中で最も使用頻度の低い、低信号の要素の1つを決定することはせず、そのままにしておきます。

それはコミット履歴にあるべきですが、コミット履歴にあるだけでなく、新しい開発者を雇うことを想像してください。新しい開発者がプロ​​ジェクトの過去10年間のすべてのコミットメッセージを読むことを期待していますか？

次に、コードの変更ではなく状況を言います。「ドキュメンテーション」コミットを行い、「リビジョン5432からのコミットメッセージが正しくない、現在の状況」の行にコミットメッセージを追加できますか。

あなたのチームのコミュニケーション方法はわかりませんが、これを言う最も効果的な方法は、最初にチームのメールグループに送信してメールを送信することです。

皆さん、SDK v xyzを使用することはできません。Fooバッファーがオーバーフローし、Barサービスがクラッシュするためです。バージョンxyyに固執する

それが私たちがここでやったことであり、そこにメッセージを届ける最も信頼できる方法です。本当に面倒なことをしたい場合（そして、電子メールシステムで許可されている場合）、電子メールの「開封確認」をリクエストしてください。

チーム全体に伝えたら、より詳細なドキュメントをチームwikiに入れる必要があります。これは、ドキュメントの構造によって異なります。アプリケーションの依存関係と要件に特化したセクションがある場合は、追加するのに適した場所です。

この種の問題を文書化する追加の場所は、ソースコード自体である場合がありますが、常に機能するとは限りません。SDK version ...が1つまたは2つの明白な場所でのみ参照されている場合、アップグレードしないことに関するメモを含めることができます。

ソース管理のファイル履歴は非常に長くなる可能性があり、開発者によっては1日に複数のエントリが存在する場合があります。1週間休暇を過ごしている人には、1週間分のコミット履歴を読む時間がありません。READMEファイルはもう少し中心的であり、人々はそれを読む傾向があるため、より良い場所ですが、誰もが実際にREADMEを読むことを保証することはできません。まあ、彼らはそれが変更されたのを見たら彼らはかもしれないと思う

このような何かがコミットコメントに入れられるべきでしたが、他の場所にいることからも恩恵を受けるでしょう。

アップグレードを決定する人は誰でも事実を知る必要があります。その人はソース管理に住んでいないかもしれません。SOでこの問題について誰かが読んで、それをコードベースに入れなかったとしたらどうでしょうか。

このサードパーティのSDKに関する何らかのドキュメントが必要です。

• どのような問題を解決しますか？
• なぜこの特定のものが選ばれたのですか？
• バージョン、アップグレード、テストなどに関する考慮事項
• 誰がこの決定をしますか？

このようなものがバージョン管理に組み込まれた場合があります。この情報をできる限り使用することを全員に推奨する必要があります。誰かがドキュメント、ソース管理、またはバグトラッカーのどこで検索を行うかを決定して、その件に関する可能な限り多くの情報を取得できます。さもなければ、忘れてしまいます、誰かがとにかくそれをします、そして、それが誰かの記憶を揺さぶって、すぐにそれを再び巻き戻すならば、あなたは幸運です。

履歴は、意識的にデータを探している読者向けのデータを配置するのに最適な場所であり、どこにあるべきかという一般的な感覚を持っています。検索するのではなく、ユーザーに提供する必要があるデータを配置するのは非常に悪い場所です。

履歴は、比較的分類されていないテキストの非常に大きなボディです。それらは通常、開発者に変更内容と変更理由に関する詳細情報を提供することを目的としています。探しているものがわからない限り、これは情報過多になる可能性があります。

ユーザーが探しているものがわからない場合、情報は数百のコミットログにすぐに埋もれてしまい、ユーザーの前にある情報の山を切り詰めるツールはありません。

私はこの状況を2つの基本的な問題、おそらく3つの問題があると解釈します。

• 望ましくないSDKのアップグレードにより、ソースに組み込まれ、製品に悪影響を及ぼす可能性がありました。
• 質問から：不要なアップグレードを実行した貢献者は、アップグレードしないという以前の具体的な決定を知りませんでした。

私の意見では、これらの最初のものが最も深刻です。望ましくないSDKのアップグレードがコードに組み込まれる場合、他の問題も同様です。

アップグレードを検出すると失敗する単体テストケースを追加することを誰かが提案しました。アップグレードの発生を防ぐことはできますが、これは時間の経過とともに溶岩の流れにつながる危険な道だと思います。将来のある時点で、SDKがアップグレードされて、新しい機能やバグ修正が導入されるか、古いバージョンがサポートされなくなるため、避けられないようです。そのような単体テストが失敗したときに発生する、ひっかき傷、おそらく議論さえ想像してみてください。

最も一般的な解決策は、開発プロセスを調整することだと思います。gitの場合、プルリクエストプロセスを使用します。 Subversionおよび古いツールの場合は、branchsとdiffを使用します。しかし、持っているいくつかの上級開発者が問題のこれらの種類をキャッチすることができますプロセスの前に、彼らはコードベースにそれを作成し、他の開発者に影響を及ぼします。

プルリクエストプロセスがあなたの状況で使用されていて、各プルリクエストが狭く具体的である場合、多くの時間は無駄にならなかっただろう。SDKをアップグレードするためのプルリクエストが送信され、アップグレードが不要であることをコメントして拒否されました。誰も影響を受けなかったので、SDKのアップグレードを元に戻す必要はありません。

しかし、元の質問に直接答えるために、私はすべての開発者がこのような通知のためにコードの改訂履歴全体、リリースノートなどを完全に読むことを期待することは貴重な時間の浪費であることに同意します。チームの短い電子メールの何が問題になっていますか？

考えられる3番目の問題：そもそもアップグレードが望まれないのはなぜですか？明らかに、少なくとも1人の開発者がアップグレードが良いことだと考えていました。アップグレードを遅らせる理由はたくさんありますが、悪い理由もたくさんあります。溶岩流（不必要な後方互換性コード）およびカーゴカルト（「それをアップグレードすることはできませんが、理由はわかりません」）アンチパターンを避けるように注意してください！

そのタイプの情報をコミット履歴に追加しても問題ありませんが、適切に文書化する必要があります。最近、（アトラシアンによる）confluenceの使用を開始しました。検索可能、特定のページをお気に入りなどに設定できます。

他のツールには、evernoteまたはgoogle docsの公開ノートブックがあります。

Karlの答えを拡張して、チェックインプロセス自体の一部として制限を自動的に強制するアプローチを採用します。doc / wiki / READMEを読むなど、開発者に代わって積極的なアクションを必要とせず、ひそかにオーバーライドできないものが必要です。

TFSソース管理領域では、チェックイン時にルールを実行するカスタムチェックインポリシーをコーディングできます。たとえば、保留中のチェックインで構成ファイルのバージョンを評価し、xyzに等しくない場合に失敗するポリシーを定義できます。これらのルールは、実際に開発者によるチェックインの実行を妨げ、説明的なメッセージを提供できます。ポリシーはオーバーライドできますが、これが発生するとアラートを生成できます。

代替手段は、カールが述べたように、SDKバージョンを直接的または間接的に評価する何らかのユニットテストで失敗するゲートチェックインです。

この回答は非常にTFS中心ですが、状況に応じてバージョン管理/ CIシステムに同様の機能が存在する可能性があります（TFSではない場合）。