對 Microsoft Learn 檔進行重大變更

文章
01/28/2024

重要

發佈至 Microsoft Learn 的所有存放庫都採用 Microsoft 開放原始碼規範或 .NET Foundation 行為規範。如需詳細資訊，請參閱管理辦法常見問題集 \(英文\)。若有任何問題或意見，也可以連絡 opencode@microsoft.com 或 conduct@dotnetfoundation.org。

learn.microsoft.com 使用規定涵蓋公用存放庫中檔和程式代碼範例的次要更正或釐清。如果您不是 Microsoft 的員工，任何變更都會在提取要求中產生批注，要求您提交在線貢獻許可協定（CLA）。您必須先完成線上表單，您的提取要求才會被合併。

本文說明如何使用本機工具變更 Microsoft Learn 文章，並適用於需要進行重大變更或將經常成為存放庫參與者。頻繁的參與者通常會進行中或長時間執行的變更，這些變更會經過多個組建/驗證/預備週期，或跨越數天，然後才登入提取要求（PR）。

這些參與類型的範例包括：

進行大量貢獻。例如，您的貢獻（新增、變更或刪除）可能會跨越多個發行項，而且需要在單一 PR 中認可並測試為一個工作單位。
建立與發佈新文章通常需要較強固的本機編輯器。
新增影像或更新影像，通常需要您同時建立新的 media 子目錄、建立圖像檔、更新文章中的影像連結，以及預覽本機編輯器中的 Markdown 檔案，以測試影像轉譯。
發佈數日前的文章，請先予以更新。在這些情況下，您通常需要定期整合預設分支中發生的其他變更。此項整會透過 Git Bash 和本機編輯很容易執行。如果您透過 GitHub Web 編輯器執行此動作，並等到認可變更之前，您也會執行遺失編輯的風險。
在開啟PR之後，對同一篇文章進行持續更新。雖然您可以針對此目的使用 GitHub Web 編輯器，但您可以針對同一個檔案建立多個未處理的 PR，這可能會彼此衝突。

必要條件

識別儲存您要編輯之檔的 GitHub 存放庫。
如果您沒有 GitHub 帳戶，請建立一個帳戶。
安裝 Git 和 Markdown 工具。
設定本機 Git 存放庫。
檢閱 Git 和 GitHub 基本概念（選擇性）。

建立並查看您的工作分支

若要開始，請在本機存放庫中建立新的工作分支，以擷取建議的變更。如需分支的詳細資訊背景，請參閱 Git 和 GitHub 基本概念。

本教學課程使用 Git Bash 和 Visual Studio Code，但您可以使用任何您偏好的 Git 用戶端和編輯器。

在 VS Code 中，開啟本機複製的存放庫資料夾。從 [ 檔案] 選單中，選取 [ 開啟資料夾 ]，然後流覽至您電腦上的資料夾。
從頂端功能表中選取 [檢視]，然後選取 [終端機] 以開啟整合式終端機。
在整合式終端機中，確定您位於存放庫資料夾中。
建立工作分支之前，請確定本機主要分支是生產存放庫主要分支中所有專案的最新分支。此工作可確保您的工作分支會擷取自上次同步處理之後在生產存放庫中發生的任何變更。
1. 切換至本機存放庫中的主要分支：
```
git checkout main 
```
2. 請確定您的本機主要分支是最新的：
```
git pull upstream main 
```
根據 main 建立本機工作分支：
```
git checkout -b <branch-name>
```
<branch-name> 是佔位元。當您執行命令時，請將它取代為分支的唯一且有意義的名稱，並移除角括號。
將本機工作分支推送至 GitHub 分支中的遠端分支：
```
git push origin <branch-name> -u
```
-u 選項會連結本機和遠端分支。此選項可讓您只輸入 git push 而非 git push origin <branch-name>，將認可推送至分支。

尋找來源 Markdown 檔案

若要編輯發行項，請在本機存放庫複製中尋找發行項的來源檔案。在 VS Code 中，透過檔案總管存取存放庫的 Markdown 檔案（左上方提要欄中的文件圖示）。檔案總管會顯示存放庫的資料夾結構，而且您可以流覽至您要編輯的檔案。

如果您找不到檔案，請流覽 Microsoft Learn 上的文章，然後選取 [ 編輯鉛筆] 圖示。 GitHub 存放庫中的相對資料夾位置會顯示在URL中。以下是編輯連結 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

編輯檔案

選取檔案，以在 VS Code 中開啟檔案。
執行您的變更。
選取 [檔案>儲存] 以儲存變更。使用 [全部 儲存] 一次儲存多個檔案。

認可並推送您的變更

如果您做了大量編輯或檢閱文章以取得新鮮度，請在檔案頂端的元數據區塊中更新 ms.date 。將日期格式化為mm/dd/yyyy。

您可以使用 VS Code 終端機或 VS Code UI 來認可和推送變更。

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 窗格。

您編輯的檔案會出現在右側的 [變更] 底下，以指出它已被修改。新的檔案會出現 U （未追蹤），而已刪除的檔案則會以 D 顯示。
暫存變更。將滑鼠停留在 [變更 ] + 行上，直到圖示出現為止。選取該圖示。此動作相當於 git add 命令。檔案現在會出現在 [ 分段變更 ] 區段中。
在 [訊息 ] 文本框中輸入認可訊息，例如「更新元數據日期」，然後選取複選標記。
推送認可。選取 [同步變更] 按鈕，該按鈕會出現在認可訊息區塊下方。

大功告成！您的程式代碼現在已在您的 GitHub 存放庫中啟動，並準備好開啟 PR。

需要修正您已經提交的東西嗎？很容易！只要重複上述步驟，從 編輯檔案開始，在相同的分支中進行變更，然後再次認可並推送（不需要在相同分支的後續推送上設定上游伺服器）。一般而言，分支是用來分隔工作串流，因此您不需要建立新的分支，除非您已準備好處理其他專案。

進行下一個變更

準備好進行另一個變更，與這個變更無關嗎？切換回預設分支，從上游存放庫提取以更新分支，並簽出新的分支。在 Git Bash 中執行下列命令：

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

您現在位於連結至遠端分支的新分支中，並已準備好進行更多變更。您正努力成為專家參與者！

下一步

如果您已完成上述步驟，現在是時候開啟PR ，將您的變更合併到main分支。
若要深入瞭解 Markdown 和 Markdown 延伸模組語法等主題，請檢閱 Markdown 參考。