.NET ドキュメントリポジトリに投稿する

[アーティクル]
08/10/2023

.NET ドキュメントへの貢献に関心をお寄せいただきありがとうございます。

このドキュメントでは、.NET ドキュメントサイトに掲載される記事やコードサンプルに協力する過程について取り上げています。投稿には、誤字の修正のような簡単なものから、新しい記事のような複雑なものまであります。

.NET ドキュメントサイトは複数のリポジトリから構築されています。以下は一例です。

投稿のガイドライン

ドキュメントに対するコミュニティの投稿に感謝します。 .NET ドキュメントを共同作成する際に留意する必要がある適用規則のいくつかを次の一覧に示します。

巨大な pull request を送信しないでください。代わりに、問題を提出し、ディスカッションを開始して、大量の時間を費やす前に方向について同意が得られるようにしてください。
記事にはインラインでサンプルコードを含めないでください。
記事に埋め込むコードにはスニペットプロジェクトを使ってください。
以下に示す手順とボイスおよびトーンのガイドラインに従ってください。
テンプレートファイルを作業の開始点として使用してください。
記事に取り掛かる前に、フォークに個別のブランチを作成してください。
GitHub フローに従います。
ご自分の共同作成についてブログ投稿およびツイート (または同類の作業) を行います。

このようなガイドラインに従うことにより、ご自分にとっても Microsoft にとってより望ましいエクスペリエンスが確保されます。

貢献プロセス

手順 1: 新しいコンテンツを書き込んだり、既存のコンテンツを完全に改訂したい場合は、自分が何をしたいかを説明する問題を開きます。 docs フォルダーのコンテンツはセクションで構成され、それらが目次 (TOC) に反映されます。 TOC のどこにトピックを配置するかを明確にします。提案に対するフィードバックを得ます。

または

既存の Issue を選択し、それに対処します。また、開示状態の Issue を参照して、関心があるイシューの対処に志願することもできます。

最初の問題として適しているものを探すには、good first issue ラベルでフィルター処理します。
コミュニティでの共同作成に適した問題を探すには、help wanted ラベルでフィルター処理します。これらの Issue には、通常、最小限のコンテキストが必要です。
経験豊富な共同作成者が、関心のある任意の Issue に対処できます。

関心のある Issue が見つかったら、それが開示されているかどうかをたずねるコメントを追加します。

作業するタスクを選択したら、GitHub アカウントを作成し、手順 2 に進みます。

手順 2: 必要に応じて /dotnet/docs リポジトリ (または投稿先のリポジトリ) をフォークし、変更用のブランチを作成します。

小さな変更については、「ブラウザーで編集」を参照してください。

手順 3: この新しいブランチで変更を行います。

新しいトピックの場合は、このテンプレートファイルを開始点として使用できます。このファイルには、作成のガイドラインが含まれ、作成者情報など、記事ごとに必要なメタデータについても説明されています。 Microsoft Learn コンテンツで使われる Markdown 構文の詳細については、「Markdown のリファレンス」を参照してください。

手順 1 で、ご自分の記事について特定した TOC の場所に対応するフォルダーに移動します。そのフォルダーには、そのセクション内のすべての記事のマークダウンファイルが格納されています。必要に応じて、ご自分のコンテンツ用のファイルを格納する新しいフォルダーを作成します。そのセクションのメインの記事は index.md と呼ばれます。

画像とその他の静的なリソース用に、記事を含むフォルダー内に media という名前のサブフォルダーを作成します (まだ存在していない場合)。 media フォルダーの中に、記事の名前のサブフォルダーを作成します (インデックスファイル以外)。ファイルの配置場所の詳細については、「フォルダー構造の例」セクションを参照してください。

コンパイルしない構造体を示す場合を除き、記事にはインラインでコードを含めないでください。代わりにコードスニペット プロジェクトを使い、コード拡張機能を使ってコードを含めます。そうすることで、お客様のサンプルコードは Microsoft の CI システムによって確実に検証されます。

コードスニペットについては、ご自分の記事が格納されているフォルダー内に snippets というサブフォルダーを作成します (それがまだ作成されていない場合)。 snippets フォルダー内に、記事の名前を使用してサブフォルダーを作成します。ほとんどの場合、3 つの主要な .NET 言語 (C#、F#、Visual Basic) すべてに対してコードスニペットを用意することになります。その場合は、3 つのプロジェクトそれぞれに対して csharp、fsharp、vb という名前のサブフォルダーを作成します。 docs/csharp、docs/fsharp.core、または docs/visual basic フォルダーの下にある記事のスニペットを作成する場合、スニペットは 1 つの言語のみになるため、[language] サブフォルダーを省略できます。ファイルの配置場所の詳細については、「フォルダー構造の例」セクションを参照してください。

コードスニペットは、記事で説明されている概念を示すコードに注目した小さなサンプルです。ダウンロードと探索を目的とした大規模なプログラムは、dotnet/samples リポジトリに配置する必要があります。完全なサンプルについては、サンプルの共同作成に関するセクションを参照してください。

手順 4: ご利用のブランチからデフォルトブランチに pull request (PR) を送信します。

重要

この時点で、コメントオートメーション機能は、すべての .NET ドキュメントリポジトリで使用できません。この PR は .NET ドキュメントチームのメンバーによって確認およびマージされます。

各 PR は、通常、複数の issue が同じ PR 修正に関連する場合を除き、一度に 1 つの issue に対処する必要があります。 PR では、1 つまたは複数のファイルを変更できます。複数のファイルで複数の修正を行う場合は、PR を分けることが推奨されています。

ご自分の PR で既存の issue を修正する場合は、PR 記述に Fixes #Issue_Number キーワードを追加します。これにより、PR がマージされるときに、問題が自動的に閉じられます。詳細については、「Linking a pull request to an issue using a keyword」 (キーワードを使用して pull request を issue にリンクする) を参照してください。

.NET チームが PR を確認し、変更を承認するために必要な他の更新や変更があるかどうかをお知らせします。

手順 5: チームによって説明されたとおりに、ご自分のブランチに必要な更新を加えます。

フィードバックが適用され、ご自分の変更が承認されると、その PR は Maintainer によってデフォルトブランチにマージされます。

Microsoft によって定期的にすべてのコミットがデフォルトブランチからライブブランチにプッシュされるので、.NET ドキュメントで自分の投稿をライブで確認できるようになります。通常、Microsoft は営業日には毎日発行しています。

フォルダー構造の例

docs
  /about
  /core
    /porting
      porting-overview.md
      /media
        /porting-overview
          portability_report.png
        /shared ...
      /snippets
        /porting-overview
          /csharp
            porting.csproj
            porting-overview.cs
            Program.cs
          /fsharp
            porting.fsproj
            porting-overview.fs
            Program.fs
          /vb
            porting.vbproj
            porting-overview.vb
            Program.vb
        /shared
          /csharp ...
          /fsharp ...
          /vb ...

Note

スニペットの下にある言語のフォルダーは、1 つの言語のみが想定されている言語ガイド領域では必要ありません。たとえば、C# ガイドでは、すべてのスニペットが C# であることを前提としています。

上記の構造には、1 つのイメージ (portability_report.png) と、porting-overview.md の記事に含まれているコードスニペットを含む、3 つのコードプロジェクトが含まれています。

"snippets と shared" フォルダーは、前の例の porting フォルダーなど、同じ親フォルダー内の複数の記事にまたがる可能性があるスニペットに使用します。 shared フォルダーを使用するのは、特定の理由がある場合だけです。たとえば、複数の記事から参照される XAML コードは、記事固有のフォルダー内でコンパイルすることはできません。

これらの記事が同じ親フォルダー (前の例の porting フォルダーなど) にある場合は、複数の記事でメディアを共有することもできます。この shared フォルダーは、可能な場合は回避し、意味を持つ場合にのみ使用してください。たとえば、デモを行うアプリに対して共通の読み込み画面を共有する、あるいは複数の記事で再利用される Visual Studio のダイアログを共有することは意味を持ちます。

重要

歴史的な理由により、含まれているスニペットの多くは、dotnet/docs リポジトリの /samples フォルダーに格納されています。記事に大きな変更を加える場合は、それらのスニペットを新しい構造に移動する必要があります。一方、小さな変更については、スニペットを移動することを心配する必要はありません。

サンプルに投稿する

コンテンツをサポートするコードについては、次のように区別しています。

サンプル: 閲覧者は、サンプルをダウンロードして、実行できます。すべてのサンプルは、完全なアプリケーションまたはライブラリである必要があります。サンプルでライブラリが作成される場合は、単体テストまたは閲覧者がコードを実行できるアプリケーションが含まれている必要があります。多くの場合、サンプルでは複数のテクノロジ、機能、またはツールキットが使用されます。各サンプルの readme.md には、各サンプル内で適用されている概念について詳細を確認できるように、記事への参照が含まれています。
スニペット: は、小規模な概念やタスクを示します。コンパイルされますが、完全なアプリケーションであることを意図するものではありません。正しく実行される必要はありますが、代表的なシナリオに適したアプリケーションの例ではありません。その代わり、単一の概念または機能を表現するために、可能な限り小さくなるように設計されます。これらは、単一のコード画面に収める必要があります。

サンプルは dotnet/samples リポジトリに格納されています。 Microsoft では、samples フォルダーの構造と docs フォルダーの構造が一致しているモデルを目指して努力しています。従っている基準は次のとおりです。

最上位レベルのフォルダーは、docs リポジトリ内の最上位レベルのフォルダーと対応します。たとえば、docs リポジトリには machine-learning/tutorials フォルダーがあり、samples/machine-learning/tutorials フォルダーには機械学習のチュートリアル用のサンプルが含まれます。

さらに、core フォルダーと standard フォルダーの下のすべてのサンプルは、NET Core によってサポートされているすべてのプラットフォーム上でビルドされ、実行される必要があります。 CI ビルドシステムにはそれが適用されます。最上位の framework フォルダーには、Windows 上でのみビルドされ、検証されたサンプルが含まれます。

サンプルプロジェクトは、特定のサンプルに対応する可能な限り広範囲のプラットフォーム上でビルドされ実行される必要があります。それは実際には、可能な限り .NET Core ベースのコンソールアプリケーションをビルドすることを意味します。 Web フレームワークまたは UI フレームワークに固有のサンプルでは、必要に応じてそれらのツールが追加される必要があります。たとえば、Web アプリケーション、モバイルアプリ、WPF または WinForms アプリなどがあります。

Microsoft は、すべてのコードに対応するように CI システムを整えることを目標に取り組んでいます。サンプルに対して更新プログラムを作成する場合は、各更新プログラムを必ずビルド可能なプロジェクトに含めます。理想的には、サンプル上に正確性のテストも追加します。

ご自分で作成した完全なサンプルには、readme.md ファイルを含める必要があります。このファイルには、サンプルの簡単な説明 (1 つまたは 2 つの段落) を含める必要があります。 Readme.md で、このサンプルを探索することで何を学習できるかを閲覧者に通知する必要があります。 Readme.md ファイルには、.NET ドキュメントサイト上に公開されているドキュメントへのリンクも含める必要があります。リポジトリ内の特定のファイルをそのサイトのどこにマップするかを判断するには、リポジトリパスの /docs を https://zcusa.951200.xyz/dotnet に置き換えます。

ご自分のトピックには、サンプルへのリンクも含まれます。 GitHub 上のサンプルのフォルダーに直接リンクしてください。

新しいサンプルを作成する

サンプルは、ダウンロード用の完全なプログラムとライブラリです。これらは、スコープ内では小さくなることがありますが、ユーザーが自分で調査して実験できるようにするための概念を示しています。サンプルのガイドラインに従うと、閲覧者がダウンロードして探索できるようになります。各ガイドラインの例として、Parallel LINQ (PLINQ) サンプルを確認してください。

使用するサンプルは、ビルド可能なプロジェクトの一部とする必要があります。可能な限り、プロジェクトは .NET Core によってサポートされているすべてのプラットフォーム上でビルドされる必要があります。ただし、プラットフォーム固有の機能またはプラットフォーム固有のツールを実演するサンプルの場合は例外です。
整合性を維持するために、使用するサンプルはランタイムコーディングスタイルに準拠する必要があります。

さらに、新しいオブジェクトのインスタンス化を必要としないものを実演する場合は、インスタンスメソッドではなく static メソッドの使用をお勧めします。
使用するサンプルには、適切な例外処理を含める必要があります。その例外処理によって、サンプルのコンテキスト内でスローされる可能性が高いすべての例外が処理される必要があります。たとえば、Console.ReadLine メソッドを呼び出してユーザー入力を取得するサンプルには、入力文字列が引数としてメソッドに渡されるときの適切な例外処理を使用する必要があります。同様に、使用するサンプルでメソッド呼び出しの失敗が予想される場合は、結果としてスローされる例外を処理する必要があります。 Exception や SystemException などの基本クラスの例外ではなく、メソッドによってスローされる特定の例外を常に処理します。

サンプルを作成するには:

Issue を提出するか、または作業する既存の Issue にコメントを加えます。
使用するサンプルで実演する概念を説明するトピックを記述します (例: docs/standard/linq/where-clause.md)。
使用するサンプルを作成します (例: WhereClause-Sample1.cs).

そのサンプルを呼び出す Main エントリポイントを使用して Program.cs を作成します。それがそこに既に存在する場合は、サンプルの呼び出しを追加します。

public class Program
{
    public void Main(string[] args)
    {
        WhereClause1.QuerySyntaxExample();

        // Add the method syntax as an example.
        WhereClause1.MethodSyntaxExample();
    }
}

.NET SDK を使用してインストールすることができる .NET CLI を使用して任意の .NET スニペットまたはサンプルを構築します。使用するサンプルを作成し実行するには:

sample フォルダーに進み、エラーをチェックするために次をビルドします。
```
dotnet build
```
使用するサンプルを実行します。
```
dotnet run
```
使用するサンプルのルートディレクトリに readme.md を追加します。

このファイルでは、コードの概説を含めると共に、サンプルを参照している記事にユーザーの目を向ける必要があります。 readme.md の先頭には、サンプルの参照に必要なメタデータが含まれている必要があります。ヘッダーブロックには、次のフィールドが含まれている必要があります。
```
---
name: "really cool sample"
description: "Learn everything about this really cool sample."
page_type: sample
languages:
  - csharp
  - fsharp
  - vbnet
products:
  - dotnet-core
  - dotnet
  - dotnet-standard
  - aspnet
  - aspnet-core
  - ef-core
---
```
- languages コレクションには、サンプルで使用できる言語のみを含める必要があります。
- products コレクションには、サンプルに関連する製品のみを含める必要があります。

特別な記載のない限り、すべてのサンプルは .NET によってサポートされている任意のプラットフォーム上のコマンドラインから構築されます。 Visual Studio に固有のサンプルであり、Visual Studio 2017 以降を必要とするサンプルがいくつかあります。さらに、サンプルの中にはプラットフォーム固有の機能を示し、特定のプラットフォームを必要とするものもあります。他に、.NET Framework を必要とし、Windows プラットフォーム上で実行され、Framework 対象バージョン用の Developer Pack を必要とするサンプルとスニペットもあります。

C# の対話型エクスペリエンス

記事に含めるすべてのスニペットで、ソース言語を示す言語タグを使用します。 C# の短いコードスニペットでは、csharp-interactive 言語タグを使用して、ブラウザー内で実行する C# スニペットを指定できます (インラインコードスニペットでは csharp-interactive タグを使用し、ソースから取り込まれるスニペットの場合は、code-csharp-interactive タグを使用します)。これらのコードスニペットで、記事内にコードウィンドウと出力ウィンドウを表示します。ユーザーがスニペットを実行すると、インタラクティブコードの実行から得られた出力がすべて出力ウィンドウに表示されます。

C# インタラクティブエクスペリエンスによって、スニペットを操作する方法が変わります。訪問者は、スニペットを実行して結果を表示することができます。スニペットまたは対応するテキストに出力に関する情報を含める必要があるかどうかは、複数の要因によって決まります。

スニペットを実行することなく、期待される出力を表示するケース

初心者向けの記事では、出力を提供して、閲覧者が期待される応答と自分の作業の出力を比較できるようにする必要があります。
スニペットの出力がトピックに不可欠な場合、その出力を表示する必要があります。たとえば、書式付きテキストに関する記事では、スニペットを実行することなく、テキスト書式を表示する必要があります。
スニペットと期待される出力の両方が短い場合は、出力を表示することを検討してください。それによって、少し時間を節約できます。
現在のカルチャまたはインバリアントカルチャが出力にどのように影響するかを説明する記事では、予想される出力を説明する必要があります。 Linux ベースのホスト上では、対話型 REPL (Read Evaluate Print Loop) が実行されます。既定のカルチャとインバリアントカルチャでは、オペレーティングシステムが異なるコンピューター上では生成される出力が異なります。 Windows、Linux、および Mac の各システム上での出力を、記事で説明する必要があります。

期待される出力をスニペットから除外するケース

記事内のスニペットで生成される出力が大きい場合、コメントにそれを含めるべきではありません。スニペットが実行されると、コードがわかりにくくなります。
記事内にトピックを示すスニペットがあるが、理解するために出力が不可欠であるとは言えない場合。例として、クエリの構文を説明するために LINQ クエリを実行するコードで、実行すると出力コレクション内のすべての項目が表示されるコードがあります。

Note

一部のトピックがここで指定したすべてのガイドラインに現在のところ従っていないことに気づかれているのではないでしょうか。 Microsoft では、サイト全体で一貫性の達成に向けて取り組んでいます。その特定の目標に向けて現在追跡中の未解決の問題の一覧をご確認ください。

英語以外のコンテンツへの投稿

機械翻訳 (MT) コンテンツの投稿は、現在受け入れられていません。 MT コンテンツの品質を向上させるため、ニューラル MT エンジンに移行しました。人間が翻訳した (HT) コンテンツへの投稿は受け付けています。これは、ニューラル MT エンジンをトレーニングするために使用されるため、ご協力ください。時間の経過と共に、HT コンテンツへの投稿により、HT と MT の両方の品質が向上します。 MT トピックには、トピックの一部が MT であることを示す免責事項が含まれており、編集が無効になっているため [編集] ボタンが表示されません。

Note

ほとんどのローカライズされたドキュメントは、GitHub を介してフィードバックを送信したり編集したりする機能を備えていません。ローカライズされたコンテンツに関するフィードバックを提供するには、https://aka.ms/provide-feedback フォームを使用します。

共同作成者ライセンス条項

ご自分の PR がマージされる前に、.NET Foundation 貢献者使用許諾契約書 (CLA) に署名する必要があります。これは、.NET Foundation 内のプロジェクトに対して 1 回だけ実行する必要があります。貢献者使用許諾契約書 (CLA) について詳しくは、Wikipedia を参照してください。

契約: .NET Foundation Contributor License Agreement (CLA)

前もって契約に署名する必要はありません。 PR は通常どおり、複製、フォーク、送信できます。 PR が作成されると、CLA ボットで分類されます。変更が小さい場合 (たとえば、入力ミスの修正)、PR には cla-not-required というラベルが適用されます。それ以外の場合は、cla-required に分類されます。ご自分が CLA に署名した後、現在以降のすべての pull request には cla-signed ラベルが付けられます。

次の方法で共有

.NET ドキュメントリポジトリに投稿する

投稿のガイドライン

貢献プロセス

フォルダー構造の例

サンプルに投稿する

新しいサンプルを作成する

C# の対話型エクスペリエンス

スニペットを実行することなく、期待される出力を表示するケース

期待される出力をスニペットから除外するケース

英語以外のコンテンツへの投稿

共同作成者ライセンス条項

フィードバック

その他のリソース

次の方法で共有

.NET ドキュメント リポジトリに投稿する

投稿のガイドライン

貢献プロセス

フォルダー構造の例

サンプルに投稿する

新しいサンプルを作成する

C# の対話型エクスペリエンス

スニペットを実行することなく、期待される出力を表示するケース

期待される出力をスニペットから除外するケース

英語以外のコンテンツへの投稿

共同作成者ライセンス条項

フィードバック

その他のリソース

.NET ドキュメントリポジトリに投稿する