生成されたドキュメントはGitリポジトリに保存する必要がありますか？

jsdocsのようなツールを使用すると、コード内のコメントに基づいてコードベースに静的なHTMLファイルとそのスタイルが生成されます。

これらのファイルをGitリポジトリにチェックインするか、.gitignoreで無視する必要がありますか？

特定のニーズがない場合、バージョン管理にチェックインされた他のファイルを使用してビルドツールからビルド、再作成、構築、または生成できるファイルはチェックインしないでください。ファイルが必要な場合、他のファイルから（再）ビルドできますソース（通常、ビルドプロセスの一部として）。

したがって、これらのファイルは.gitignoreで無視する必要があります。

私のルールは、リポジトリを複製して「ビルド」ボタンを押すと、しばらくしてからすべてがビルドされるということです。生成されたドキュメントでこれを実現するには、2つの選択肢があります。誰かがこれらのドキュメントを作成してgitに入れるか、開発マシンで必要なソフトウェアを正確にドキュメント化し、「ビルド」を押すことを確認しますbuttonは、私のマシン上にすべてのドキュメントを作成します。

生成されたドキュメントの場合、ヘッダーファイルに1つの変更を加えただけでドキュメントが変更されるはずです。各開発者のマシンでこれを行うと、誰かがそれを更新したときだけでなく、常に正しいドキュメントが必要になります。他にも、何かを生成するのに時間がかかり、複雑で、ライセンスが1つしかないソフトウェアが必要な場合などがあります。その場合は、1人にgitに入れる責任を与える方が良いでしょう。

@Curt Simpson：すべてのソフトウェア要件を文書化することは、私が多くの場所で見たよりもはるかに優れています。

これらのファイルは、生成するデータが既に存在するため、チェックインしないでください。データを2回（DRY）保存する必要はありません。

CIシステムがある場合は、おそらくドキュメントをビルドし、そのビルド用に保存して、Webサーバーに公開できます。

それらを何らかのリポジトリー（同じまたは異なるリポジトリー、できれば自動的に生成されたもの）に保管する利点の1つは、文書に対するすべての変更を確認できることです。これらのdiffは、ソースコードのdiffよりも読みやすい場合があります（具体的には、実装の変更ではなく仕様の変更のみに関心がある場合）。

ただし、他の回答で説明したように、ほとんどの場合、ソース管理にそれらを含める必要はありません。

無視されます。とにかくリポジトリのユーザーがそれらを再構築できるようにしたいと思うでしょう、そしてそれはドキュメントが常に同期していることを確実にするという複雑さを取り除きます。すべてを1か所にまとめて、何もビルドする必要がない場合、ビルドされたアーティファクトを1か所にまとめない理由はありません。ただし、ソースリポジトリは実際にはこれを行うのに適した場所ではありませんが、複雑さはほとんどの場所よりも痛いためです。

展開プロセスによって異なります。ただし、生成されたファイルをリポジトリにコミットすることは例外であり、可能であれば回避する必要があります。次の質問の両方にYesで回答できる場合、ドキュメントのチェックインが有効なオプションである可能性があります。

• ドキュメントは本番環境の要件ですか？
• 展開システムには、ドキュメントを構築するために必要なツールがありませんか？

これらの条件が当てはまる場合は、おそらくレガシーシステムまたは特別なセキュリティ制約のあるシステムで展開しています。別の方法として、生成されたファイルをリリースブランチにコミットし、マスターブランチをクリーンに保つことができます。

場合によります。それらのドキュメントの場合：

• のように、リポジトリの一部である必要がある場合readme.md、gitリポジトリに保存することをお勧めします。これらの状況を自動化された方法で処理するのは難しい場合があるためです。

• CIシステムのように、自動化された方法でビルドおよび更新する方法がなく、一般ユーザー向けに表示することを意図している場合は、gitリポジトリに保存することをお勧めします。

• それらを構築するのに多くの時間を要し、それらを保持する正当な理由があります。

• 一般ユーザー（ユーザーマニュアルなど）に表示されることを目的としており、構築にかなりの時間がかかりますが、以前のドキュメントにアクセスできなくなり（オフライン）、それをgitリポジトリに保持する正当な理由があります。

• 一般ユーザー向けに表示されることを意図しており、その変更/進化の履歴を表示する必要があります。以前のバージョンのドキュメントをコミットしたまま、以前のバージョンにリンクした新しいバージョンをビルド/コミットする方が簡単です。正当。

• すべてのチームがコミットされる特定の受け入れられた理由があり、それをgitリポジトリに保持する正当な理由がある。（私たちはあなたのコンテキストを知りません、あなたとあなたのチームはします）

他のシナリオでは、無視してください。

ただし、それらをgitリポジトリに保持する正当な理由がある場合は、チームが直面している別の大きな問題の兆候である可能性があります。（CIシステムまたは同様の恐ろしいパフォーマンスの問題がなく、構築中にダウンタイムが発生するなど）

バージョン管理の原則として、「プライマリオブジェクト」のみをリポジトリに保存し、「派生オブジェクト」は保存しないでください。

ルールには例外があります。つまり、派生オブジェクトを必要とするリポジトリのコンシューマがあり、それらを生成するために必要なツールがないことが合理的に予想される場合です。材料の量が扱いにくいなど、他の考慮事項が重くなりますか？（プロジェクトがすべてのユーザーにツールを提供するだけの方が良いでしょうか？）

これの極端な例は、コンパイラがその言語自体で書かれている珍しいプログラミング言語を実装するプロジェクトです（よく知られた例には、OcamlまたはHaskellが含まれます）。コンパイラのソースコードのみがリポジトリにある場合、誰もビルドできません。仮想マシンで実行できるコンパイラのコンパイルバージョンがないため、そのコンパイラのソースコードをコンパイルできます。さらに、言語の最新の機能はコンパイラソース自体ですぐに使用されるため、ビルドには常に最新バージョンのコンパイラが必要です。 1か月前には存在しなかった言語機能を使用します。この状況では、コンパイラーのコンパイル済みバージョンをほぼ確実にリポジトリーにチェックインし、最新の状態に保つ必要があります。