リポジトリの README を作成する

  • [アーティクル]

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

Git リポジトリには、コードの内容と、コードの使用を開始する方法を閲覧者が理解できるように、readme ファイルが必要です。 readme は次の対象ユーザー向けに作成する必要があります。

  • コードを実行するだけのユーザー。
  • コードをビルドしてテストする開発者。 開発者もユーザーです。
  • コードに変更を送信する共同作成者。 共同作成者は開発者でありユーザーでもあります。

readme はプレーンテキストではなく Markdown で記述します。 Markdown を使用すると、必要に応じてテキストの書式設定、画像の追加、必要に応じて readme からその他のドキュメントへのリンクを簡単に行うことができます。

ここでは、この形式を使用し、参照とインスピレーションのために、次の 3 つのすべての対象ユーザーに向けた優れた readme をいくつか紹介します。

概要を作成する

プロジェクトを表す簡単な説明で readme を開始します。 プロジェクトにユーザー インターフェイスがある場合は、概要にスクリーンショットまたはアニメーション GIF を追加します。 コードが別のアプリケーションまたはライブラリに依存している場合は、それらの依存関係を概要またはそのすぐ下に必ず記載してください。 特定のプラットフォームでのみ実行されるアプリとツールには、readme のこのセクションに記載されているサポートされているオペレーティング システムのバージョンが必要です。

ユーザーが作業を開始できるように支援する

readme の次のセクションで、ユーザーが自分のシステムでコードを起動して実行する方法を案内します。 コードの使用を開始するための重要な手順に集中してください。 ユーザーが簡単にアクセスできるように、前提条件ソフトウェアの必要なバージョンへのリンクを作成します。 複雑なセットアップ手順がある場合は、それを readme の外部で文書化し、それらへのリンクを作成します。

コードの最新リリースを入手できる場所を示します。 バイナリ インストーラーまたはパッケージ ツールを使用してコードを使用する手順が最適です。 プロジェクトがライブラリまたは API のインターフェイスである場合は、基本的な使用法を示すコード スニペットを配置し、そのスニペット内のコードのサンプル出力を示します。

開発者にビルド手順を提供する

readme の次のセクションを使用して、リポジトリの新しいクローンからコードをビルドし、含まれているテストを実行する方法を開発者に示します。 次の手順で行います。

  • コードのビルドに必要なツールの詳細を説明し、クリーン ビルドを取得するためにツールを構成する手順を文書化します。
  • 難しいまたは複雑なビルド命令をドキュメント内の別のページに分割し、必要に応じてリンクを作成します。
  • 作成した手順を実行して、その手順が新しい共同作成者に対して機能することを確認します。

これらの手順を頼りにする開発者は、しばらくプロジェクトに携わっていなかった自分かもしれないことに留意してください。

ビルドが成功したら、ソース コードで提供されるテスト ケースを実行するコマンドを提供します。 開発者はこれらのテスト ケースを参考にして、コードを変更しても壊れないことを確認します。 優れたテスト ケースは、開発者が新しい機能を追加するときに独自のテスト ケースを構築するために使用できるサンプルとしても機能します。

ユーザーの投稿を支援する

readme の最後のセクションは、ユーザーと開発者が問題の報告に関与したり、コードを改善するためのアイデアを提案したりするのに役立ちます。 ユーザーは、バグを公開したり、機能を要求したり、コードを使用する際のヘルプを受けたりできるチャンネルにリンクされている必要があります。

開発者は、コーディングまたはテストのガイドラインや pull request の要件など、変更を投稿するために従う必要があるルールを把握する必要があります。 pull request を受け入れるために共同作成者の同意が必要な場合、またはコミュニティの行動規範を実施する場合、このセクションにこのプロセスをリンクするか文書化する必要があります。 コードがどのライセンスに基づいてリリースされているかを明記し、ライセンスのフルテキストにリンクします。