淘汰說明文件

隨著 Fuchsia 不斷演進，我們需要淘汰已淘汰功能的文件或過時文件。

制定淘汰時間表

移除文件前，請務必先制定淘汰時間表並通知使用者。一般而言，建議在 6 個月的淘汰期過後移除文件。

如要開始淘汰程序並通知使用者，請按照下列步驟操作：

• 在 Markdown 檔案中淘汰文件
• 在導覽中淘汰文件

在 Markdown 檔案中淘汰文件

如要在 Markdown 檔案中將文件標示為已淘汰，請按照下列步驟操作：

1. 找出以 # 為前置字串的網頁標題。例如：

   # Deprecating documentation
   

2. 在文件標題下方新增下列 include 陳述式。例如：

   # Deprecating documentation
   
   {% include "fuchsia-src/_common/_deprecation_notice.md" %}
   
   

3. 向使用者說明淘汰原因等資訊。此外，請一併說明取代已淘汰功能的新工具或功能。

4. 在導覽中將文件標示為已淘汰。

在導覽中停用文件

如要在 _toc.yaml 檔案中將文件標示為已淘汰，請按照下列步驟操作：

1. 找出參照您要淘汰文件集的 _toc.yaml 檔案。例如：

   - title: "Deprecating documentation"
     path: /docs/contribute/docs/deprecating-docs.md
   

2. 在網頁標題下方新增 status: deprecated 鍵/值組合。例如：

   - title: "Deprecating documentation"
     status: deprecated
     path: /docs/contribute/docs/deprecating-docs.md
   

3. 將變更 (文件和目錄淘汰) 提交至 Fuchsia 存放區。

將頁面重新導向至淘汰通知

淘汰時間表結束後，請刪除這些網頁並重新導向。

如要刪除網頁並重新導向：

1. 搜尋參照您要移除網頁的任何連結。例如：

   grep -r "/docs/contribute/docs/deprecating-docs.md" ~/fuchsia/docs/
   

   這會列出透過 grep 指令連結至該網頁的所有文件。

2. 更新或移除說明文件中參照您要淘汰頁面的任何連結。

3. 使用 git rm 移除要淘汰的文件。例如：

   git rm docs/contribute/docs/deprecating-docs.md
   

4. 找出參照文件的 _toc.yaml 檔案，然後移除已淘汰文件的項目。

5. 確認 doc-checker 通過測試。執行 fx format-code 即可執行文件檢查工具：

   fx format-code
   

   修正 doc-checker 可能發出的任何問題。

6. 在 /docs/_common/_deprecated-docs.yaml 檔案中，為已淘汰的網頁建立重新導向，將使用者導向淘汰通知頁面。此外，也請列出註解，說明已淘汰的功能和淘汰日期。例如：

   # May 13th, 2022
   # Deprecating documentation around deprecation
   - from: /docs/contribute/docs/deprecating-docs.md
     to: /docs/contribute/docs/deprecation-notice.md
   

7. 將變更提交至 Fuchsia 存放區。