Azure DevOps Services |Azure DevOps Server |Azure DevOps Server 2022
コードが何を行い、どのように使い始めることができるかを閲覧者が把握できるように、Git リポジトリには README ファイルが必要です。 README ファイルは、次の対象ユーザーに読み上げられます。
- コードを実行したいユーザー。
- コードをビルドしてテストする開発者。 開発者もユーザーです。
- コードに変更を加えたいと考える貢献者。 共同作成者は、開発者とユーザーの両方です。
プレーン テキストではなく 、Markdown で README ファイルを記述します。 Markdown を使用すると、テキストの書式設定、画像の含め、README ファイルからより多くのドキュメントへのリンクを簡単に行うことができます。
この形式を使用し、3 人の対象ユーザー全員と話す README ファイルをいくつか次に示します。 参考とインスピレーションのためにそれらを使用してください:
[前提条件]
| カテゴリ | Requirements |
|---|---|
| プロジェクトへのアクセス権 | プロジェクトのメンバー。 |
| アクセス許可 | - プライベート プロジェクトのコードを表示する: 少なくとも Basic アクセス。 - プライベート プロジェクトのコードを複製または投稿する: 共同作成者セキュリティ グループのメンバー、またはプロジェクト内の対応するアクセス許可。 - ブランチまたはリポジトリのアクセス許可を設定する: 管理アクセス許可 は、ブランチまたはリポジトリのアクセス許可です。 - 既定のブランチを変更する: 編集ポリシー はリポジトリのアクセス許可です。 - リポジトリをインポートする: プロジェクト管理者 セキュリティ グループのメンバーまたは Git プロジェクト レベルの [リポジトリ の作成 ] アクセス許可が [許可] に設定されています。 詳細については、「Git リポジトリのアクセス許可を設定する」を参照してください。 |
| サービス | リポジトリが有効になっています。 |
| ツール | Optional.
az reposコマンドを使用する: Azure DevOps CLI。 |
注
パブリック プロジェクトでは、 利害関係者 アクセス権を持つユーザーは、コードの表示、複製、投稿など、Azure Repos へのフル アクセス権を持ちます。
| カテゴリ | Requirements |
|---|---|
| プロジェクトへのアクセス権 | プロジェクトのメンバー。 |
| アクセス許可 | - コードの表示: 基本 アクセスが最低限必要です。 - コードの複製または投稿: 共同作成者 セキュリティ グループのメンバー、またはプロジェクト内の対応するアクセス許可。 |
| サービス | リポジトリが有効になっています。 |
概要を作成する
プロジェクトを説明する簡単な説明で README ファイルを開始します。 プロジェクトにユーザー インターフェイスがある場合は、概要にスクリーンショットまたはアニメーション GIF を追加します。 コードが別のアプリケーションまたはライブラリに依存している場合は、それらの依存関係を概要またはその下に必ず記載してください。 特定のプラットフォームでのみ実行されるアプリとツールには、README ファイルのこのセクションで説明されているサポートされているオペレーティング システムのバージョンが必要です。
ユーザーが作業を開始できるように支援する
README ファイルの次のセクションでは、ユーザーが自分のシステムでコードを起動して実行する手順を説明します。 コードを使い始めるのに不可欠な手順に集中してください。 ユーザーが簡単に入手できるように、必要なバージョンの前提条件ソフトウェアにリンクします。 複雑なセットアップ手順がある場合は、README ファイルの外部でこれらの手順を文書化し、それらにリンクします。
最新リリースを入手する場所を読者に伝えます。 次のいずれかの項目を指定します。
- バイナリ インストーラーまたは事前構築済みパッケージへのリンク。
- パッケージ マネージャーを使用したインストール手順 (たとえば、npm install、pip install、dotnet add package)。
プロジェクトがライブラリまたは API ラッパーである場合は、基本的な使用方法を示す最小限のコード スニペットを含め、その後に予想される出力を含めます。 この情報は、読者がセットアップを確認し、ライブラリの動作をひとめで把握するのに役立ちます。
開発者向けのビルド手順を提供する
README ファイルの次のセクションを使用して、リポジトリの新しい複製からコードをビルドし、含まれているテストを実行する方法を開発者に示します。 次の手順を実行します:
- コードをビルドするために必要なツールの詳細を説明し、クリーン ビルドを取得するように構成する手順を文書化します。
- 高密度または複雑なビルド命令をドキュメント内の別のページに分割し、必要に応じてリンクします。
- 手順を書きながら実行して、新しい参加者にとって手順が有効であることを確認します。
あなたは、しばらくの間プロジェクトに取り組まない後、これらの手順に依存している開発者である可能性があることに注意してください。
ビルドが成功した後にソース コードで提供されるテスト ケースを実行するコマンドを含めます。 開発者はこれらのテスト ケースに頼って、変更を加える際にコードを中断しないようにします。 優れたテスト ケースは、開発者が新しい機能を追加するときに独自のテスト ケースを構築するために使用できるサンプルとしても機能します。
ユーザーの投稿を支援する
README ファイルの最後のセクションは、ユーザーと開発者が問題を報告し、コードを改善するためのアイデアを提案するのに役立ちます。 ユーザーは、バグを開いたり、機能を要求したり、コードを使用してヘルプを受けたりできるチャネルにリンクする必要があります。
開発者は、コーディング/テストのガイドラインやプル要求の要件など、変更を加えるために従う必要がある規則を把握する必要があります。 pull request を受け入れるか、コミュニティの行動規範を適用するために共同作成者契約が必要な場合は、このプロセスをこのセクションにリンクするか、このセクションに記載する必要があります。 コードがリリースされるライセンスを指定し、ライセンスの全文にリンクします。