淘汰說明文件

隨著 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. 將變更 (文件和 TOC 淘汰) 提交至 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 以執行 doc-checker：

   fx format-code
   

   修正 doc-checker 可能信號的所有問題。

6. 在 [/docs/_common/_deprecate-docs.yaml][deprecate-docs] 檔案中，為已淘汰的網頁建立重新導向淘汰通知頁面。同時加入一則註解，列出已淘汰日期的已淘汰功能。例如：

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

7. 提交 Fuchsia 存放區的變更。