对 Microsoft Learn 文档进行主要更改

重要

发布到 Microsoft Learn 的所有存储库均遵循 Microsoft 开放源代码行为准则或 .NET 基础行为准则。有关详细信息，请参阅行为准则常见问题解答。或如有任何疑问或意见，请联系 opencode@microsoft.com 或 conduct@dotnetfoundation.org。

learn.microsoft.com 使用条款涵盖了公共存储库中对文档和代码示例所做的较小的更改和说明。如果你不是 Microsoft 的员工，那么任何更改会在拉取请求中生成一条注释，要求提交一份在线参与许可协议 (CLA)。在合并拉取请求之前，你需要填写这份在线表单。

本文介绍了如何使用本地工具更改 Microsoft Learn 文章，适用于需要进行主要更改的参与者，或者频繁编辑向存储库的参与者。频繁参与者通常会不断进行或持续更改，这些更改会经过多个构建/验证/暂存周期或跨越数天，然后才进行拉取请求 (PR) 签核和合并。

这些类型的参与示例包括：

进行大型供稿。例如，你的更改（增补/更改/删除）可以跨越多篇文章，且需要作为单个拉取请求中的一个工作单元进行提交和测试。
创建和发布新文章，这通常需要更为稳健的本地编辑器。
添加新图像或更新图像，这通常要求同时创建新的 media 子目录、创建图像文件、更新文章中的图像链接、在本地编辑器中预览 Markdown 文件来测试图像呈现情况。
在发布前更新一段时间内的文章。在这些情况下，通常需要定期集成默认分支中的其他更改。通过 Git Bash 和本地编辑可更轻松地完成集成。如果通过 GitHub Web 编辑器完成合并，还可能丢失编辑内容，请在提交更改前等待一段时间。
在 PR 打开后对同一篇文章进行持续更新。尽管可以使用 GitHub 网页编辑器实现此目的，但可能会为同一文件创建多个未完成的 PR，这可能会相互冲突。

先决条件

首先，在本地存储库中创建一个新的工作分支，以获取你所建议的更改。有关分支的更多背景信息，请参阅 Git 和 GitHub 基础知识。

本教程使用 Git Bash 和 Visual Studio Code，但可以使用喜欢的任何 Git 客户端和编辑器。

在 Visual Studio Code 中，打开本地克隆的存储库文件夹。在“文件”菜单中，选择“打开”文件夹并导航到计算机上的文件夹。
在顶部菜单中，选择“视图”，然后选择“终端”以打开集成终端。
在集成终端中，确保位于存储库文件夹中。
在创建工作分支之前，确保本地主分支与生产存储库主分支中的所有内容保持同步。此任务可确保工作分支捕获自上次与生产存储库同步以来在生产存储库中发生的任何更改。
1. 切换到本地存储库中的主分支：
```
git checkout main 
```
2. 确保本地主分支为最新：
```
git pull upstream main 
```
基于主分支创建本地工作分支：
```
git checkout -b <branch-name>
```
<branch-name> 是占位符。运行该命令时，请将其替换为分支的唯一且有意义的名称，并删除尖括号。
将本地工作分支推送到 GitHub 分支中的远程分支：
```
git push origin <branch-name> -u
```
-u 选项链接本地和远程分支。通过此选项，只需输入 git push 而不是 git push origin <branch-name> 即可将提交推送到分支。

要编辑文章，请在本地存储库克隆中找到文章的源文件。在 VS Code 中，通过文件资源管理器（左上方边栏中的文档图标）访问该存储库的 Markdown 文件。文件资源管理器显示存储库的文件夹结构，可导航到要编辑的文件。

如果找不到该文件，请参阅 Microsoft Learn 上的文章并选择“编辑”铅笔图标。 URL 中会显示 GitHub 存储库中的相对文件夹位置。以下是“编辑”链接 URL 的示例：

   https://github.com/Microsoft/azure-docs/blob/main/articles/azure-functions/functions-overview.md

以下是此 URL 的示例文件位置。

   C:\GitHub\*\azure-docs\articles\azure-functions\functions-overview.md

如果对文章进行了大量编辑或审阅，请在文件顶部的元数据块中更新 ms.date。日期格式为 mm/dd/yyyy。

可以使用 VS Code 终端或 VS Code UI 提交和推送更改。

运行 git status 命令，验证更改的文件列表中是否只显示编辑的文件。
```
git status
```
运行 git add 命令，后跟文件路径和文件名，以暂存更改的文件。
```
git add folder-name/file-name.md
```
如果更改了多个文件，请针对每个文件输入 git add 命令。

或者，可以运行 git add . （注意 add 后面的句点）来自动暂存所做的所有更改。此方法速度较快，但由于包含意外所做的更改，可能会导致出现问题。
再次运行 git status 以确认已暂存的更改。
运行 git commit 命令，后跟提交消息以将更改保存到本地克隆存储库中。
```
git commit -m "your commit message"
```
运行 git push 以推送更改。
```
git push
```

可以使用 VS Code 的 Git 集成功能创建和推送提交。请记住在同一台计算机上继续工作。如果更换计算机，将无法继续使用最新版本的工作分支。

确保本地存储库仍具有相同的工作分支签出。在 VS Code UI 中，分支显示在左下角。分支名称也可用作切换分支的按钮。
在 VS Code 左侧栏中，选择分支工具以查看“源代码管理：Git”窗格。

编辑的文件将出现在“更改”下，右侧带有一个“M”，表示该文件已被修改。新文件显示为“U”（未跟踪），已删除的文件显示为“D”。
暂存更改。将鼠标悬停在“更改”行上，直到出现 + 图标。选择此图标。此操作相当于 git add 命令。此时，文件将出现在“暂存更改”部分。
在“消息”文本框中输入提交消息（如“更新元数据日期”），然后选中复选标记。
推送提交。选择出现在提交消息块下方的“同步更改”按钮。

大功告成！你的代码现在将在 GitHub 存储库中，并可用于打开拉取请求。

需要修复已提交的内容？操作起来非常简单！只需重复上述步骤，从“编辑文件”开始，在同一分支中进行更改，然后重新提交并推送即可（无需对同一分支的后续推送设置上游服务器）。通常，分支用于分隔工作流，因此无需创建新分支，除非已准备好处理其他操作。

准备好进行另一项与此无关的更改？切换回默认分支，从上游存储库拉取，以更新分支，然后签出新分支。在 Git Bash 中运行以下命令：

git checkout main
git pull upstream main
git checkout -b "branchname"
git push origin <branch-name> -u

现在，你位于链接到远程分支的新分支中，并且已准备好进行更多更改。你正朝着成为一位专家级参与者的道路上稳步前进！