弃用文档

随着 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 以运行文档检查工具：

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