コミット履歴を使用して、重要な情報を開発者に伝える必要がありますか？
最新バージョンからのサードパーティSDKのロールバックに関する会議中に、開発者がコミット履歴で最新バージョンを使用してはならないというフラグを立てていることが指摘されました。
一部の開発者は、これは悪い習慣であり、代わりにソースファイル（つまり、// Don't upgrade SDK Version x.y.z, see ticket 1234）またはプロジェクトレベルのREADMEファイル。他の人たちは、コミット履歴はプロジェクトのドキュメントの一部であるため、とにかく読むべきなので、そのような情報の受け入れ可能な場所であると主張しました。
コミット履歴を使用して重要な情報を他の開発者に伝える必要がありますか、またはそのような情報をプロジェクトREADMEまたは関連するソースファイルのコメントなどの別の場所に複製する必要がありますか？
サードパーティSDKの新しいバージョンへのアップグレードを確認する場合、最後に確認する場所は、ソース管理システムのhistoryです。
製品が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コメントに対してコードベースを精査する必要はありません。
問題チケットにリンクすることで、好奇心旺盛な開発者はどのように失敗したかを知ることができ、後で再検討する可能性があります。それがないと、かなり静的になり、二度と更新されない可能性があります。
重要で直感的でない情報は、人々が情報を検討する際にどこを見ているかを文書化する必要があります。
私が取り組んできたチームとプロジェクトについては、新しいバージョンが失敗した理由についてのコメントを付けてロールバックをコミットします。新しいバージョンが修正されたら、バックログストーリーを追加してアップグレードを再試行します。ライブラリがリンクされているビルドシステム/ビルドスクリプトにコメントを追加します。
ロールバックは、プロジェクトの履歴を調べるときに将来の開発者にコンテキストを提供します。バックログストーリーは、このアップグレードの必要性をプロジェクトのアクティブな部分として保持します。ビルドシステムのコメントは、ライブラリが最終的に更新されるときに変更を加える必要がある場所に適切です。
コードではコメントせず、READMEにも追加しません。アップグレードを試みることを考えている開発者は、これらの部分を見ていません。そこに追加した場合、ライブラリの問題が最終的に修正され、アップグレードが完了したら、削除する必要があります。このステップはしばしば忘れられます。その結果、プロジェクトに対して逆効果のメモが作成されます。
プロジェクトのセットアップやフローが異なる場合、答えは異なる場合があります。重要なのは、アップグレードのための作業を行うときに開発者がそれを見る場合に、情報を正しく配置することです。そうすれば、アップグレードのタイミングが適切でない場合、開発者はそれを見て停止し、適切なタイミングになると、開発者はそれを見てメモを削除し、将来の開発者を混乱させません。
私は マシューのコメント 彼の重要なアイデアを回答で強調することで、もっと注目したいと思いました。 SDKをアップグレードしたくない理由があり、その理由は単体テストでキャプチャする必要があります。リビジョン番号のチェックではなく、実際の根本的な理由。
たとえば、新しいバージョンにバグがあるとしましょう。そのバグをチェックする単体テストを作成します。 SDKのバグを後で修正すれば、アップグレードはスムーズに行われます。互換性のないAPIの変更がある場合は、コードが新しいAPIをサポートしているか、SDKが古いAPIをサポートしているかを確認するテストを記述します。これは単体テストというよりは統合テストの詳細ですが、それでも実行可能であるはずです。
私の会社は1日あたり50以上のコミットを生成しており、私たちは正確には巨大ではありません。すべての開発者がすべてのコミットメッセージを読んだとしても、正直ではありませんが、記録されたコミット履歴が必要なのは、人々がそれを覚えていないためです。そして、問題がなければ、人々は戻って歴史を読むことはありません。そして、彼らが知っている限り、まだ発生していないアップグレードの問題を疑う理由はありません。
近い将来、作業の重複を防ぐために必ずメールを送信し、ビルドスクリプトとREADMEまたは正誤表）にそれを書き留めてください。ただし、特に新しいバージョンの問題が微妙な場合はトラブルシューティングに時間がかかり、それを明確にする方法が必要です。つまり、単体テストです。
「発見した重要な情報をコミットメッセージを介してチームの他のメンバーに伝えるべきですか？」と質問を再キャストします。私はそれがノーであることを明らかにしていると思うので、そうすべきではありません。私は多くのことを伝えようと努力します（これは、私の経験では、ほとんどの開発チームが積極的な努力を払う必要があることです）、間違いなく、落とし穴を作らないように、または嘘をつくことのないように、できる限りのことをします。
このような発見に至る一連のアクションがチケットによってトリガーされた場合は、チケットを更新し（これを知っているはずの人に可視性があることを確認します）、おそらく対面で（おそらく少なくとも、「うーん、デイモンが更新について何か言ったと思う」というしつこい感覚を誰かに残すには、もちろんSDKが含まれている時点でコードにコメントを残して、誰も更新できないようにしますそれを見る機会がなくても。私の開発wikiのどこかでジャムできるかどうかもわかるかもしれませんが、それは現在のチームではなく、将来の採用を視野に入れて行われています。
問題に遭遇して発見するのにかかる時間と比較して、数分しかかかりません。私は、ドキュメントの中で最も使用頻度が低く、信号の少ない部分の1つであるとは判断せず、そのままにしておきます。
それはコミット履歴にあるはずですが、コミット履歴にあるだけでなく、しばらくの間、新しい開発者を雇うことを想像してください。新しい開発者が、プロジェクトの過去10年間のすべてのコミットメッセージを読むことを期待しますか？それらのいくつかは、コードベースを理解するために重要です。
2番目に、コードの変更ではなく状況を言います。「ドキュメント」をコミットして、「リビジョン5432からのコミットメッセージが正しくありません。現在の状況です」という行に沿ってコミットメッセージを追加できますか。
あなたのチームがどのように通信しているかはわかりませんが、これを言う最も効果的な方法はfirstチームのメールグループに送信してメールで送信し、本文に「緊急」のマークを付けます
皆さん、SDK v x.y.zは使用できません。Fooバッファがオーバーフローし、Barサービスがクラッシュするためです。バージョンx.y.yに固執する
これが私たちがここで行ったことであり、メッセージをそこに届けるための最も信頼できる方法です。 本当に煩わしくなりたい場合（および電子メールシステムで許可されている場合）、電子メールで「開封確認」を要求します。
チーム全体に伝えたら、より詳細なドキュメントをチームのwikiに入力する必要があります。これは、ドキュメントの構成方法によって異なります。アプリケーションの依存関係と要件に特化したセクションがある場合、それを追加するのに適しています。
この種の問題を文書化するための追加の場所は、ソースコード自体にある可能性がありますが、常に機能するとは限りません。 SDK version ...は1つまたは2つの明白な場所でのみ参照されます。アップグレードしないことについてのメモを含めることができます。
ソース管理のファイル履歴は非常に長くなる可能性があり、開発者によっては、1日に複数のエントリを持つ可能性があります。 1週間休暇を取った人は、1週間分のコミット履歴を読む時間がないかもしれません。 READMEファイルは少し中心的であり、人々はそれを読む傾向があるため、より良い場所ですが、誰もが実際に読むことを保証することはできませんread README。まあ、私は彼らがそうだと思います可能性があります彼らがそれが変更されているのを見た場合.
このような何かがコミットコメントに入れられるべきでしたが、他の場所にいることからも利益を得ます。
アップグレードを決定する人は誰でも、事実を知る必要があります。その人はソース管理に住んでいない可能性があります。誰かがこの問題についてSOで読んだことがあり、コードベースに決して入れなかったとしたらどうでしょうか？
このサードパーティのSDKに関するドキュメントが必要です。
- それはどのような問題を解決しますか？
- なぜこれが選ばれたのですか？
- バージョン、アップグレード、テストなどに関して、どのような考慮が必要か。
- 誰がこの決定をしますか？
このようなものがバージョン管理に組み込まれたケースがあり、この情報をできるだけ多くの人に使用することをお勧めします。ドキュメント、ソース管理、バグトラッカーのどこで検索を行うかを決定できるのはチームだけです。さもなければ、あなたは忘れるでしょう、とにかく誰かがそれをするでしょう、そしてそれが誰かの記憶を揺さぶって、すぐにそれを再びロールバックするならば、あなたは幸運です。
履歴は、意識的に探している読者向けのデータを置くのに最適な場所であり、どこにあるべきかという一般的な感覚を持っています。検索するのではなく、ユーザーに提供する必要があるデータを置くのは非常に悪い場所です。
履歴は、比較的並べ替えられていないテキストの非常に大きな本体です。これらは通常、何が変更されたか、なぜ変更されたのかについての詳細情報を開発者に提供することを目的としています。探しているものがわからなければ、これは情報過多になる可能性があります。
ユーザーが何を探しているのかわからない場合、情報は何百ものコミットログの下にすぐに埋もれ、その前にある情報の山を整理するツールがありません。
私はこの状況を2つの基本的な問題、おそらく3つの問題があると解釈します。
- 望ましくないSDKのアップグレードがソースになり、製品に悪影響を及ぼす可能性があります。
- 質問から：不要なアップグレードを実行した寄稿者は、アップグレードしないという以前の特定の決定について知りませんでした。
私の意見では、これらの最初のものは最も深刻です。不要なSDKのアップグレードがコードに組み込まれる可能性がある場合は、他の問題も可能になります。
誰かが、アップグレードを検出すると失敗する単体テストケースを追加することを提案しました。これはアップグレードの発生を防ぎますが、これは危険な経路であり、時間の経過とともに 溶岩流 につながると私は思います。今後、SDKがアップグレードされたり、新機能やバグ修正が導入されたり、古いバージョンがサポートされなくなったりすることは避けられません。そのような単体テストが失敗したときに発生する頭を悩ませる、おそらくは引数を想像してみてください。
最も一般的な解決策は、開発プロセスを調整することだと思います。 gitの場合、 pull request プロセスを使用します。Subversionおよび古いツールの場合は、branchsおよびdiffを使用します。しかしsome上級開発者がこの種の問題をキャッチできるプロセスbeforeがコードベースに組み込まれ、他の開発者に影響を与えます。
あなたの状況でプルリクエストプロセスが使用されていて、各プルリクエストが狭く具体的である場合、多くの時間は無駄になりませんでした。 SDKをアップグレードするプルリクエストが送信され、アップグレードは不要であるというコメントで拒否されました。他の誰も影響を受けることはなく、SDKアップグレードを元に戻す必要はありません。
しかし、元の質問に直接答えるには、すべての開発者がコードやリリースノートなどの変更履歴全体を完全に読んで、このような通知を完全に読むことを期待することは貴重な時間の浪費であることに同意します。チームの短い電子メールの何が問題になっていますか？
考えられる3番目の問題：そもそもなぜアップグレードが望まれないのですか？明らかに、少なくとも1人の開発者が、アップグレードは良いことだと考えていました。アップグレードを遅らせる理由はたくさんありますが、悪い理由もたくさんあります。溶岩流（不必要な後方互換性コード）と 貨物カルト （「これはアップグレードできませんが、理由はわかりません」）アンチパターンを回避するように注意してください！
そのタイプの情報をコミット履歴に追加することは問題ありませんが、適切に文書化する必要があります。最近、アトラシアンによるconfluenceの使用を開始しました。検索可能で、特定のページをお気に入りとして設定できます。
他のいくつかのツールは、evernoteやgoogle docsの公開ノートブックかもしれません。
カールの答え を拡張して、チェックインプロセス自体の一部として制限を自動的に適用するアプローチを採用します。 doc/wiki/READMEを読むなど、開発者に代わって予防的なアクションを必要とせず、ひそかに上書きできないものが必要です。
TFSソース管理ランドでは、チェックイン時にルールを実行するカスタム チェックインポリシー をコーディングできます。たとえば、保留中のチェックインを含む構成ファイルのバージョンを評価し、x.y.zと等しくない場合は失敗するポリシーを定義できます。これらのルールは、実際に開発者がチェックインを実行することを防ぎ、説明的なメッセージを提供できます。ポリシーは上書きできますが、これが発生したときにアラートを生成することは可能です。
Karlが述べたように、SDKのバージョンを直接または間接的に評価する何らかの形式の単体テストで失敗するゲートチェックインが別の方法です。
この回答がTFS中心であることに感謝しますが、状況に応じてバージョン管理/ CIシステムに同様の機能が存在する可能性があります（TFSでない場合）。