弃用文档

随着 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 代码库。