菜单
文档breadcrumb arrow Writers' Toolkitbreadcrumb arrow 写作breadcrumb arrow 废弃或移除
开源
最后评审时间：2024 年 5 月 16 日

废弃或移除内容

废弃（Deprecation）是指计划在未来版本中移除某个特性或产品。在废弃到移除期间，该特性或产品处于维护状态。

移除（Removal）是指产品或特性被移除且不再支持。

处理这些情况的流程因产品或特性的淘汰或维护方式而异。

您应在计划移除特性前提前两个小版本通知用户。例如，如果您计划在 Grafana v9.5 中移除某个特性，则应在 Grafana v9.3 中开始向用户传达该信息。

为了确保用户充分了解其产品或特性的废弃阶段，您应该：

  • 在产品的“最新内容”、文档以及必要时在 UI 中使用说明告知客户废弃信息。
  • 通过发送电子邮件至 gtm-se-field-engineering@grafana.com 或在 Slack 频道 #field-engineering-with-nomads 中联系，通知现场团队。
  • 移除完成后更新这些说明。
  • 在 Grafana 社区 Slack 和 论坛 中宣布废弃。
  • 通知客户体验 (CX) 和解决方案工程 (Solution Engineering) 团队。

废弃

场景：“您计划在未来版本中移除该特性或产品。”

示例文本

markdown 
{{< admonition type="caution" >}}
Starting with <RELEASE>, <PRODUCT OR FEATURE NAME> is deprecated.
It will be removed in a future release.
{{< /admonition >}}

如果您知道具体版本，请用版本号替换“未来”。

移除

场景：“您已移除某个特性。”

示例文本

markdown 
{{< admonition type="warning" >}}
<PRODUCT OR FEATURE NAME> is removed.
It is no longer deployed, enhanced, or supported.
{{< /admonition >}}

文档废弃

场景：在某些情况下，您可能会独立于特性废弃而废弃文档。

示例文本

markdown 
{{< admonition type="caution" >}}
Starting with release <VERSION>`, the <TOPIC TITLE> documentation will no longer be published because <RATIONALE>.
Link to documentation, if it exists.
{{< /admonition >}}

具体示例

注意

自 Grafana 9.2 起，将不再发布发布说明，因为它们与“最新内容”文档和 CHANGELOG 中的内容重复。

如何处理废弃

以下流程描述了如何处理废弃。此流程适用于废弃特性及其关联文档被废弃的情况，也适用于独立于特性废弃而废弃文档的情况。

您可能需要在文档*和* UI 中添加前面的说明。

  1. 作者、工程师或产品经理确定受废弃影响的文档。

    如果您的团队有专门的作者，请与您的作者合作。如果您没有指定的作者，请联系 Fiona Peers Artiaga。

  2. 如果您没有指定的作者，工程师或产品经理请与 Grafana Labs 文档团队沟通，提供受影响文档的链接、废弃的理由以及时间安排。请将您的消息发布到 #docs 频道。

    Grafana Labs 文档团队的分类流程会通知作者任何待处理的文档废弃。

  3. 在废弃文档的 PR（Pull Request）中，作者、工程师或产品经理应在评论中使用前面表格中标识的文档废弃语言说明废弃文档的理由，如果用户可以参考替代文档，请提供链接。

    GitHub 会自动将与这些文档关联的作者指定为 PR 的审阅者。

  4. 作者要么起草 PR，要么审阅并批准 PR，并在“最新内容”草稿文档中添加废弃通知。

    如果可用，请包含链接。

文档移除

搜索引擎更新其索引需要时间。在搜索引擎更新其索引之前，用户从搜索结果链接到该页面时会看到 404 错误。

为了加快重新索引过程，请在 Slack 中联系 #seo 频道。您需要提供已移除页面的完整 URL，然后团队可以将其提交给搜索引擎索引进行移除。