参与 .NET 文档存储库

项目
02/06/2024

感谢你对参与 .NET 文档的关注！

本文档介绍参与托管在 .NET 文档站点上的文章和代码示例撰写的过程。参与内容可简（更正拼写错误），可繁（编写新文章）。

.NET 文档站点的构建以多个存储库为基础。其中部分存储库如下：

参与原则

我们感谢社区对文档做出的贡献。以下列表显示了在为 .NET 文档做出贡献时应牢记的部分指导规则：

请勿发出大型拉取请求。可以提出问题并发起讨论，以便我们在你花费大量时间前确定方向。
请不要在文章中包含示例代码内联。
请务必使用包含要嵌入到文章中的代码的代码片段项目。
请务必遵循这些说明以及语音语调准则。
请务必使用模板文件作为工作的起点。
请务必在处理文章前，在分叉上创建一个单独的分支。
请务必遵循 GitHub 流。
如果你愿意的话，请发布有关参与的博客和推文（或者诸如此类）！

遵循这些指南可确保你和我们都能获得更好的体验。

参与流程

步骤 1：如果你有兴趣编写新内容或彻底修改现有内容，请提交一个问题来说明具体目的。 docs 文件夹中的内容会划分为多个部分，而这些部分会反映在目录 (TOC) 中。定义主题在 TOC 中的位置。获取对建议的反馈。

-或-

选择现有问题并解决该问题。可查看未解决问题列表，并自愿处理感兴趣的主题：

对于好的优先问题，通过 good first issue 标签进行筛选。
对于适合社区参与的问题，通过 help wanted 标签进行筛选。这些问题通常需要的上下文很少。
经验丰富的参与者可以处理任何感兴趣的问题。

当你找到要处理的问题时，可以添加评论，询问是否未解决。

选择要处理的任务后，创建一个 GitHub 帐户，然后继续执行步骤 2。

步骤 2：按需对 /dotnet/docs 存储库（或正在参与的任意存储库）进行分叉，并为更改创建一个分支。

对于小幅更改，请参阅在浏览器中编辑。

步骤 3：对该新分支进行更改。

如果要新建主题，可以使用此模板文件作为起点。它包含编写指南，还介绍了每篇文章所需的元数据，例如作者信息。有关 Microsoft Learn 内容中所用 Markdown 语法的详细信息，请参阅 Markdown 参考。

导航到与步骤 1 中为文章确定的 TOC 位置相对应的文件夹。该文件夹包含该部分中的所有文章的 Markdown 文件。如有必要，可以创建一个新文件夹来放置内容文件。该部分的主要文章称为“index.md”。

对于图像和其他静态资源，在包含项目的文件夹内创建名为“媒体”的子文件夹（如果尚不存在）。在“媒体”文件夹中，使用项目名称创建一个子文件夹（索引文件除外）。有关将文件放置在何处的详细信息，请参阅示例文件夹结构部分。

请不要在文章中包含代码内联，除非正在演示未编译的构造。请改用代码片段项目，并使用代码扩展包含代码。这可确保示例代码由 CI 系统验证。

对于代码片段，请在包含你的文章的文件夹中创建一个名为“snippets”的子文件夹（如果尚不存在）。在“代码片段”文件夹中，创建包含文章名称的子文件夹。在大多数情况下，你将具有全部三种主要的 .NET 语言（C#、F# 和 Visual Basic）的代码片段。在此情况下，请为三个项目中的每一个分别创建名为“csharp”、“fsharp”和“vb”的子文件夹。如果要在 docs/csharp、docs/fsharp 或 docs/visual-basic 文件夹下为一篇文章创建代码片段，此代码片段只能采用一种语言，你才能忽略语言子文件夹。有关将文件放置在何处的详细信息，请参阅示例文件夹结构部分。

代码片段很小，侧重于展示文章中所述概念的代码的示例。用于下载和查看的更大型程序应放置在 dotnet/samples 存储库中。所有示例都在参与撰写示例部分中有所介绍。

步骤 4：将拉取请求 (PR) 从该分支提交到默认分支。

重要

任何 .NET 文档存储库中的评论自动化功能均暂不可用。 .NET 文档团队成员将评审和合并 PR。

通常，每个 PR 一次应解决一个问题，除非有多个问题与同一 PR 修复相关。 PR 可以修改一个或多个文件。如果要处理不同文件的多个修补程序，最好是使用单独的 PR。

如果 PR 可修复现有问题，请在 PR 描述中添加 Fixes #Issue_Number 关键字。以此，在合并 PR 时将自动关闭该问题。有关详细信息，请参阅使用关键字将拉取请求链接到问题。

.NET 团队将审核 PR，并告知是否需要进行任何其他更新/更改才能批准。

步骤 5：与团队讨论后，对分支进行必要的更新。

反馈应用后且更改得到审批后，维护程序会将 PR 合并为默认分支。

我们将定期从默认分支将所有提交推送到实时分支，然后便能够在 .NET 文档中实时查看你的参与。通常我们会在工作周期间每日发布。

文件夹结构示例

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 ...

注意

语言指南区域不需要代码段下的语言文件夹，它只会采用一种语言。例如，在 C# 指南中，假定所有代码片段都是 C#。

上面所示结构包含一张图像 portability_report.png，还有三个包含代码片段的代码项目，它们都包含在 porting-overview.md 文章中。

snippets/shared 文件夹用于可能跨同一父文件夹内的多篇文章的代码片段，如前一示例中的 porting 文件夹。仅在有特定原因时才使用 shared 文件夹，例如，XAML 代码由多篇文章引用但不能在 article-specific 文件夹中编译。

如果这些文章位于同一父文件夹中，则还可以在多篇文章之间共享媒体，如前一示例中的 porting 文件夹。应尽可能避免使用此 shared 文件夹，并且应仅在有意义时才使用。例如，共享所演示应用的同一加载屏幕，或共享在多篇文章中重复使用的 Visual Studio 对话框。

重要

由于历史原因，很多包含的片段存储在 dotnet/docs 存储库的 /samples 文件夹下。如果要对某篇文章进行重大更改，应将这些片段移到新的结构。但是，对于较小的更改，不必移动代码片段即可进行。

参与示例撰写

我们对支持我们内容的代码进行了以下区分：

示例：读者可以下载并运行示例。所有示例应都为完整的应用程序或库。在示例创建库的位置，它应包括单元测试或允许读者运行代码的应用程序。它们通常使用多种技术、功能或工具包。每个示例的 readme.md 文件都将引用文章，使你能够深入了解每个示例中涉及的概念。
代码段：说明较小的概念或任务。它们可以编译，但并不是完整的应用程序。它们应正常运行，但不是典型方案的示例应用程序。相反，它们旨在尽可能小，以说明单个概念或功能。这些应只是一个屏幕的代码。

示例存储在 dotnet/samples 存储库中。我们正在努力建立一个示例文件夹结构与文档文件夹结构匹配的模型。我们将遵循如下标准：

顶层文件夹与 docs 存储库中的顶层文件夹相匹配。例如，文档存储库具有“机器学习/教程”文件夹，机器学习教程示例位于“示例/机器学习/教程”文件夹。

此外，“核心”和“标准”文件夹下的所有示例都应在 .NET Core 支持的所有平台上构建和运行。我们的 CI 生成系统会强制此要求。顶级“框架”文件夹包含仅在 Windows 上生成和验证的示例。

示例项目应在针对给定示例可能的最广泛的一组平台上生成和运行。实际上，这表示在可能的位置生成基于 .NET Core 的控制台应用程序。特定于 Web 或 UI 框架的示例应根据需要添加这些工具。示例有 Web 应用程序、移动应用、WPF 或 WinForms 应用等。

我们正在努力实现适用于所有代码的 CI 系统。当对示例进行任何更新时，请确保每个更新都属于可生成项目。理想情况下，还可添加针对示例正确性的测试。

创建的每个完整示例都应包含“readme.md”文件。此文件应包含示例的简短说明（一个或两个段落）。 “readme.md”应告知读者通过研究此示例他们将了解到的内容。 “Readme.md”文件还应包含到 .NET 文档站点上实时文档的链接。要确定存储库中给定文件映射到该站点的位置，请将存储库路径中的 /docs 替换为 https://learn.microsoft.com/dotnet。

主题还将包含该示例的链接。直接链接到 GitHub 上的示例文件夹。

编写新示例

示例是可供下载的完整程序和库。它们的范围可能很小，但以一种用户能自行浏览和试验的方式对概念进行了展示。示例指南确保读者可下载和浏览。请查看并行 LINQ (PLINQ) 示例，它们是每份指南中的例子。

示例必须属于可生成项目的一部分。如果可能，应在 .NET Core 支持的所有平台上生成项目。此情况的例外是演示平台特定功能或平台特定工具的示例。
示例应符合运行时编码样式，以保持一致性。

此外，演示不需要初始化新对象的内容时，我们首选 static 方法，而不是实例方法。
示例应包括适当的异常处理。它应处理可能在示例的上下文中引发的所有异常。例如，当输入字符串以参数形式传递给方法时，调用 Console.ReadLine 方法以检索用户输入的示例应使用适当的异常处理。同样，如果示例需要方法调用失败，则必须处理导致的异常。请始终处理方法引发的特定异常，而不是基类异常，例如 Exception 或 SystemException。

创建示例：

提交问题，或向正在处理的现有问题添加注释。
编写解释示例中演示的概念的主题（例如：docs/standard/linq/where-clause.md）。
编写示例（例如：WhereClause-Sample1.cs）。

使用调用示例的主要入口点创建 Program.cs。如果已有一个，则添加对示例的调用：

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

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

你可以使用 .NET CLI 生成任意 .NET 代码片段或示例，而该工具可随 .NET SDK 一起安装。生成并运行示例：

转到示例文件夹和生成，查看其中的错误：
```
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 版本的开发人员工具包。

C# 交互式体验

文章中包含的所有代码片段均使用语言标记来指示源语言。采用 C# 的短代码片段可使用 csharp-interactive 语言标记来指定在浏览器中运行的 C# 代码片段。（内联代码片段使用 csharp-interactive 标记，对于获取自源的代码片段，则使用 code-csharp-interactive 标记。）这些代码片段在文章中显示为代码窗口和输出窗口。输出窗口显示用户运行代码片段后，执行交互式代码时所生成的任何输出。

C# 交互式体验改变了代码片段的处理方法。访问者可运行代码片段来查看结果。有许多因素可帮助确定代码片段或对应的文本是否应包含输出的相关信息。

在哪些情况下应显示预期输出而不运行代码片段

面向初学者的文章应提供输出，以便读者能够将其工作输出与预期答案进行比较。
如果代码片段的输出对于主题而言至关重要，则应显示该输出。例如，介绍格式化文本的文章应显示文本格式而不运行代码片段。
如果代码片段和预期输出均简短，应考虑显示该输出。它可以节省一些时间。
说明当前区域性或固定区域性如何影响输出的文章应解释预期输出。交互式 REPL（读取评估打印循环）在基于 Linux 的主机上运行。默认区域性和固定区域性在不同的操作系统和计算机上生成不同输出。本文应介绍 Windows、Linux 和 Mac 系统中的输出。

在哪些情况下应从代码片段中排除预期输出

如果文章中的代码片段会生成较大的输出，则不应在注释中包含该输出。运行代码片段会导致代码不明了。
文章中的代码片段演示某个主题，但其输出对于理解该主题不甚重要。例如，运行 LINQ 查询来解释查询语法，然后显示输出集合中的每个项的代码。

注意

你可能已注意到，部分主题当前不遵循此处指定的所有准则。我们正努力实现整个站点的一致性。请查看我们当前正在跟踪的有关此特定目标的未解决问题列表。

为非英语内容做出贡献

当前不接受参与机器翻译 (MT) 内容。为提高 MT 内容的质量，我们已转用一种神经 MT 引擎。我们接受并鼓励人工翻译 (HT) 内容供稿，这些内容将用于训练神经 MT 引擎。随着时间的推移，HT 内容供稿会同时提高 HT 和 MT 的质量。 MT 主题将包含一条免责声明，其中指出主题的一部分可能是机器翻译，而由于已禁止编辑，因此将不显示“编辑”按钮。

注意

大多数本地化文档不提供通过 GitHub 编辑或提供反馈的功能。若要提供有关本地化内容的反馈，请使用 https://aka.ms/provide-feedback 表单。

贡献者许可协议

在合并 PR 前，必须签署 .NET Foundation 贡献许可协议 (CLA)。对于 .NET Foundation 中的项目，只需签署一次即可。可在维基百科上详细了解贡献许可协议 (CLA)。

协议：.NET Foundation 参与者许可证协议 (CLA)

无需事先签署该协议。可如常克隆、创建分支并提交 PR。创建 PR 后，将由 CLA 自动程序对其分类。如果更改较小（例如，修复拼写错误），则 PR 将标记为 cla-not-required。其他情况下，会分类为 cla-required。签署 CLA 后，当前和所有未来的拉取请求都会被标记为 cla-signed。

通过