特定のニーズに合わせてサードパーティのライブラリを変更する必要がある場合があります。バグの修正、パフォーマンスの改善、機能の追加などです。
たとえば、JSoup と Android サポート ライブラリのソースをプロジェクトに含め、いくつかの変更を加えました。また、Android ソース コードから 2 つの Java ファイルを使用して同じことを行いました。
これをどのように文書化すればよいですか?
特定のニーズに合わせてサードパーティのライブラリを変更する必要がある場合があります。バグの修正、パフォーマンスの改善、機能の追加などです。
たとえば、JSoup と Android サポート ライブラリのソースをプロジェクトに含め、いくつかの変更を加えました。また、Android ソース コードから 2 つの Java ファイルを使用して同じことを行いました。
これをどのように文書化すればよいですか?
しないでください。ライブラリのフォークされたバージョンを維持することは、特にライブラリをアップグレードしたい場合や、何度も何度も変更をバックポートする必要がある場合に苦痛です。言うまでもなく、いつの日か誰かがあなたのバージョンを忘れて、標準バージョンを使用するようになるでしょう。
したがって、変更なしで失敗するテスト ケースを常に含めるようにしてください(コードで明らかになる外部ライブラリのバグを公開します)。
変更は常に元の作成者/メンテナに提出してください。問題を報告し、パッチを含めます。あなたの変更がルール -1 に違反する価値がある場合、それはおそらく次のリリースに含まれるでしょう。
ライブラリの元のソース ファイルを変更せずにコミットします。次に、説明メッセージとともにすべての改善/バグ修正をコミットします。できれば、あなたの(または図書館の)発券システムの説明を指す発行/チケット ID を含めてください。
このようにして、この特定のディレクトリまたはプロジェクトのコミットのリストを参照すると、何が変更されたかを簡単に確認できます。外部ライブラリをフォークして変更する必要があることをコミット メッセージだけでは説明できない場合は、いつでも issue/ticket を閲覧できます。また、理想的な世界では、このようなコミットは理想的なパッチになります (ルール 0 を参照)。
ボーナス:私はかつて、 mavenプラグインを介して外部ライブラリのフォークとパッチを自動化するという考えを持っていました. 基本的に、この架空のプラグインに、特定のライブラリに特定のパッチを適用するように指示します。Maven は、ソースを簡単にダウンロードし、リビルド、インストールして、ターゲット アーティファクトの元のバージョンの代わりに、変更されたバージョンを自動的に含めることができます。
フォークされたバイナリを維持する必要はなく、パッチが新しいバージョンに完全に適用されていれば簡単にアップグレードできます。ここで暇な人はいますか?