Skip to content

Latest commit

 

History

History
99 lines (62 loc) · 5.24 KB

CONTRIBUTING.md

File metadata and controls

99 lines (62 loc) · 5.24 KB
Raw

参与实体框架文档

下面阐述了如何向实体框架文档贡献文章和代码示例。 贡献可简单到纠正错别字，也可复杂到撰写新的文章。

如何提出简单的更正或建议

文章以 Markdown 文件的形式保存在此存储库中。 要对 Markdown 文件的内容进行简单更改，请单击浏览器窗口右上角的“编辑”链接 。 你可能需要展开“选项”栏才会看到“编辑”链接 。 按照说明创建拉取请求 (PR)。 EF 团队将对拉取请求进行审核并接受相关请求或提出更改建议。

如何提出更复杂的提交

需要对 Git 和 GitHub.com 有基本的理解。

  • 打开问题，描述想要执行的操作，例如更改现有文章或创建一个新文章。 请等待 EF 团队批准后再投入时间参与进来。
  • 为 dotnet/EntityFramework.Docs 存储库创建分支，并为所做的更改创建分支。
  • 将拉取请求 (PR) 与更改一起提交到主干。
  • 对 PR 请求反馈进行响应。

Markdown 语法

文章以 DocFx-flavored Markdown (DFM) 的形式编写，它是 GitHub-flavored Markdown (GFM) 的一个超集。 要在示例中了解 EF 文档中常用的 UI 功能的 DFM 语法和元数据，请参阅 .NET Core 存储库风格指南中的元数据和 Markdown 模板。

文件夹结构约定

图像和其他静态内容存储在网站每个区域/文件夹中的 _static 文件夹中。

代码示例存储在 samples 根文件夹。 它们采用模仿文档结构（位于 entity-framework 根文件夹下）的文件夹结构。

代码片段

文章经常使用代码片段来说明要点。 DFM 允许将代码复制到 Markdown 文件或引用单独的代码文件。 只要可行，都请使用单独的代码文件以尽量减少代码出错几率。 代码文件应存储在使用示例项目的上面所述的文件夹结构的存储库中。

下面是一些 DFM 代码片段语法示例。

将整个代码文件呈现为代码片段：

[!code-csharp[Main](../../../samples/core/saving/Program.cs)]

使用行号将文件的一部分呈现为代码片段：

[!code-csharp[Main](../../../samples/core/saving/Program.cs?range=1-10]

有关 C# 代码片段，请参阅 C# 区域。 使用区域而不是行号。 代码文件中的行号容易变化且与 Markdown 中的行号引用不同步。 可嵌套 C# 区域。 如果要引用外部区域，则片段中不呈现内部 #region 和 #endregion 指令。

呈现名为 “snippet_Example” 的 C# 区域：

[!code-csharp[Main](../../../samples/core/saving/Program.cs?name=snippet_Example)]

突出显示呈现的代码段中选定的行（通常呈现为黄色背景）：

[!code-csharp[Main](../../../samples/core/saving/Program.cs?name=snippet_Example&highlight=1-3,10,20-25)]

使用 DocFX 测试更改

使用 DocFX 命令行工具测试更改，这将创建站点的本地托管版本。 DocFX 不呈现为 docs.microsoft.com 创建的样式和站点扩展。

DocFX 需要使用 .NET Framework（对于 Windows）或 Mono（对于 Linux 或 macOS）。

Windows 说明

  • 从 DocFX 发布下载并解压缩 “docfx.zip”。

  • 将 DocFX 添加到路径。

  • 在命令行窗口中，导航到克隆的存储库（它包含 docfx.json 文件），并运行以下命令 ：

    docfx -t default --serve

  • 在浏览器中导航到 http://localhost:8080。

Mono 说明

  • 使用 Homebrew 安装 Mono - brew install mono。

  • 下载 DocFX 的最新版本。

  • 提取到 \bin\docfx。

  • 为 “docfx” 创建一个别名：

    function docfx {
  mono $HOME/bin/docfx/docfx.exe
}

function docfx-serve {
  mono $HOME/bin/docfx/docfx.exe serve _site
}

  • 在克隆存储库中运行“docfx”以生成站点，并在 http://localhost:8080 上运行“docfx-serve”以查看站点。

语气和语调

我们的目标是编写被广泛受众所理解的易懂文档。 为此，我们编写了写作风格指南，请参与者遵守。 有关详细信息，请参阅 .NET Core 存储库中的 语气和语调指南。