README テンプレート

ミッション

あなたのプロジェクトのミッションについての簡潔な(3〜5行の)説明が含まれている必要があります。このセクションのゴールは、あなたが何に取り組む予定かを述べ、外部のコントリビューターがこのプロジェクトに歓迎されそうな機能の種類をおおよそ理解できるようにすることです。 Producing Open Source Software の Mission Statement Chapter も参照してください。

はじめに

このセクションには、初めてプロジェクトを使う人に向けた、使い始めるための簡単な説明を記載します。さらに詳細なドキュメントにはここからリンクをさせましょう。

詳細

このセクションでは、以下のいずれか、またはすべてを列挙することができます。

  • ソフトウェアが対応する機能、ユースケースのリスト

  • トレードオフを解決するために使用される設計原理に関する情報

  • ユーザーレベルのドキュメントへのリンク

  • よくある質問(FAQ)に対する回答。できれば、特定の質問とその回答にリンクして、簡単に参照できるようにした形式が望ましいです。

ヘルプ

このセクションには、ユーザーとしてプロジェクトのヘルプを得る方法についての簡単なドキュメントを記述します。 イシュートラッカーをユーザーに対して指し示すようにシンプルなディレクションでもかまいません。また、アーカイブされ検索可能なチャットチャネルとメーリングリスト、オンラインのユーザーフォーラムを紹介することもできます。

参加するには

このセクションには、プロジェクトと連絡を取る方法に関する情報を含める必要があります。通常これにはアーカイブされた検索可能およびアクセス可能なコミュニケーションチャネルへのリンクが含まれます。

私たちについて

このページは、プロジェクトのトラステッドコミッターに謝意を表すのに良い場所です。 また、このプロジェクトにおいてトラステッドコミッターであることが何を意味するのかについての情報を含めるのにも良い場所です。 理想的には、組織内のすべてのプロジェクトが同じ定義を使用のが良いでしょう。その場合、すべての README が同じ定義へのリンクを貼ることになります。 このリンクを残す理由は、インナーソースのプロジェクトで働いたり貢献した経験がない、もしくは少ない同僚が、日々の仕事に必要な技術プロジェクトから会社全体の情報へのダイレクトリンクを持てるようにするためです。

コントリビューションについて

このセクションでは、初めての人がコントリビュートを始めるために知っておく必要があるすべての事柄についてドキュメント化(もしくはリンクを貼る)する必要があります。 以下のトピックのすべてがカバーされることは希ですが、あなたのプロジェクトが標準的なセットアップと何が違うのか、以前のコントリビューターが理解しにくいと感じたことに重点を置いて書いてください。

  • ソースコードを見つける方法

  • プロジェクトで助けを必要としている問題のリストを見つける方法。これらの問題は、技術的・非技術的な両方の問題になりえます。通常、これらの問題は、コントリビューターがアクセスできるイシュートラッキングシステムも掲載されます。

  • プロジェクトのアーキテクチャ、一般的なコーディング規約、テスト規約など、さらなるドキュメントへのリンク

  • 技術的なコンとリビューションについて、変更を加え、プロジェクトをビルドし、変更をテストする方法

  • 変更した内容をプロジェクトにサブミットする。

理想的には、プロジェクトにとって望ましい変更プロセスがどのようなものであるかについての情報も含めてください。コントリビューターはまずイシューを作成して提案を提出すべきなのか、それともすぐにでも変更を提出することができるのか。投稿をレビューする際に重要なことは何ですか?

さらに、プロジェクトで守りたい設計の価値観についても概要を説明しておく必要があります。これらを明示することで、トレードオフをより早く、より簡単に解決できることがよくあります。さらに、暗黙の前提に対する変更を透明化するのにも役立ちます。

時間が経つにつれて、このセクションがかなり大きくなっていることに気がつくと思います。その場合は、例えば CONTRIBUTING.mdTESTING.md のように、情報を別のファイルに移動することを考えてみてください。

最終更新