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