文档 作者工具包 贡献 贡献至“新特性”或“发布说明”

贡献至“新特性”或“发布说明”

本主题解释了收集、撰写和发布“新特性”内容的决策和行动。

此页面上的信息适用于使用“新特性”或内容管理系统 (CMS) 发布有关新功能和更新功能的说明的 Grafana 产品。但是，并非所有产品都使用“新特性”流程来发布其发布说明。例如，Grafana Tempo 的发布说明是在 Tempo 存储库中创建的。Grafana Cloud Traces 更新则通过“新特性”发布。

“新特性”文档开发流程

“新特性”内容通过网站内容管理系统 (CMS) 发布到网站上。

由于此平台旨在供整个组织使用，因此默认情况下，任何人都可以贡献并发布到“新特性”，无需审批。质量保证是贡献团队和内部利益相关者内部及之间沟通协商的结果，但在本主题的最后两节中描述了一些最佳实践指南。

“已发布”是什么意思？

重要的是要理解，在 CMS 的上下文中，“已发布”一词的含义与一般用法略有不同

• 已发布，但未上线：您的条目已完成并处于“已发布”状态，但在“Cloud 新特性”页面上不可见。
• 已发布且上线：您的条目已完成并处于“已发布”状态，并在“Cloud 新特性”页面上可见。

“新特性”发布时机

在功能可用之前，将发布说明输入到 CMS 中，提前时间取决于产品或功能的大小，通常为两到四周。

对于带版本的 Grafana 发布，请确保在交付团队指定的截止日期前将发布说明输入到 CMS 中。

这使得上市 (GTM) 团队有时间进行推广和赋能。更多信息，请参阅记录、宣布、文档、发布 (RADS) 指南。

创建“新特性”条目

准备好添加“新特性”条目时，请完成以下步骤

1. 转到网站 CMS 的“新特性”集合，并点击页面顶部的“新特性”按钮。

2. 填写 CMS 字段。

3. 点击“保存”。该条目现在处于“草稿”状态，CMS 会在 grafana/website 存储库中创建一个 Pull Request。

4. (可选) 在 GitHub 上预览您的条目。

   虽然 CMS 提供了条目的预览，但它无法渲染视频。在 GitHub 上预览您的条目可以查看视频，并在网站上下文中查看您的条目。

   • 发布日期在过去 - 您的条目将在网站生成的预览中可见。

   • 发布日期在将来 - 您的条目仅在内部 Feed 的预览中可见。要查看它，请在部署预览 URL 中，将 /docs/grafana-cloud 替换为您的条目标题。例如：https://deploy-preview-18347-zb444pucvq-uw.a.run.app/whats-new/#create-subtables-in-table-visualizations。

5. 如果您的条目已准备好发布，请继续下一步。如果您的条目需要审阅，请按照以下步骤操作

   1. 在“状态”下拉列表中，选择“审阅中”。
   2. 与您的团队协作审阅并最终确定生成的 Pull Request。

   注意

   Grafana Labs 文档团队不会自动审阅这些 Pull Request；创建“新特性”条目的团队负责确定其自己的审阅流程。

6. 在您输入的发布日期前发布您的条目。

   • 要从 GitHub 发布，请合并您的 PR。
   • 要从 CMS 发布
   1. 在“状态”下拉列表中，点击“就绪”。
   2. 在“发布”下拉列表中，点击“立即发布”。

该条目将在您输入的发布日期显示在Cloud 新特性中。如果日期在过去，则会立即显示。

对于带版本的 Grafana 发布，您在 CMS 中输入的内容将在稍后日期发布在带版本的“新特性”中。要了解为带版本的 Grafana 发布创建发布说明的过程，请参阅创建带版本的发布说明。

CMS 字段

导航至 CMS。

如果您的条目已处于“已发布”状态，您可以在 CMS 的“内容”部分下的“Cloud 新特性”中找到它。

1. 如果您的条目仍处于“草稿”或“审阅”状态，您可以在 CMS 的“工作流程”部分下的相应标题下找到它。

   • 更新您需要更改的字段。
   • 点击“保存”。该条目现在处于“草稿”状态。

2. 执行以下操作之一

3. 如果您的条目已准备好发布，请在“状态”下拉列表中选择“就绪”，然后在“发布”下拉列表中选择“立即发布”。

4. 如果您的条目需要审阅，请在“状态”下拉列表中选择“审阅中”以打开审阅 PR。有关管理审阅 PR 的更多信息，请参阅创建“新特性”条目中的步骤 3。

   • 如果您的条目已在“Cloud 新特性”中上线，并且处于带版本发布的截止日期和发布日期之间，请更新 CMS，然后联系负责创建带版本发布说明的人员。
   • 如果您的条目在 Cloud 和自行管理版本“新特性”中都已上线后需要更新，您需要更新这两个条目。

处于新发布阶段的功能

如果您之前为某个功能处于早期发布阶段时创建了“新特性”条目，并且您想宣布该功能已进入新的发布阶段，请创建一个新条目。例如，您在功能处于公开预览阶段时发布了“新特性”条目，现在该功能已全面可用。

您无需使新条目像之前那样详细。相反，您可以通过引用或链接到之前的条目来保持新条目的简洁。

创建带版本的发布说明

以下说明适用于直接负责创建带版本发布说明的人员。这通常是技术写作团队的成员。

“新特性”条目截止日期过后，创建一个分支并创建一个草稿 Pull Request，其中包含一个空的 whats-new-in-vxx-x.md 文件，用于填充下一次发布的“新特性”内容。此 PR 应包含

更新 whatsnew/_index.md

1. 更新 docs/sources/_index.md 中“新特性”磁贴上的链接和版本号

   • 新的升级指南
   • 新的重大更改页面（如果需要）
   • 暂时给 PR 打上 no-backport 标签；这可能会更改。
   • 请技术写作团队的构建工程师（通常是）从“Cloud 新特性”生成一个 Markdown 文件，并满足以下条件

2. 按相关的 Grafana 版本筛选

3. 包含每个条目的前置元数据

   • 按标签分组；具有多个标签的条目仅包含一次，按其首个标签按字母顺序分组
   • 将此 Markdown 文件的内容添加到 whats-new-in-vxx-x.md 文件中，使用标签数据对项目进行分组。
   • 如果条目中列出了内部赋能视频，但相应的 YouTube 视频尚未添加到这些条目的正文中，您需要稍后添加。为此，请在临近发布日期时从“Cloud 新特性”生成另一个 Markdown 文件，并根据新生成的文件更新 whats-new-in-vxx-x.md。

4. 在发布日期前一周，将 PR 状态从“草稿”更改为“准备审阅”，以向其他利益相关者表明该 PR 已准备好进行进一步审阅。

   审阅不得包含任何文本编辑，除非存在不准确或拼写错误，因为所有文本编辑应在将条目添加到“Cloud 新特性”时进行。如果存在任何不准确之处，需要在 Cloud 和带版本的“新特性”中进行更正。

5. 请 PM 审阅内容以调整顺序（如果需要）。

   与 PM 协作最终调整升级指南或重大更改页面。

6. 如果需要，为 PR 添加回传标签。

7. 在发布前两天，从“Cloud 新特性”获取最终生成的 Markdown 文件，并将任何必要的添加项添加到 whats-new-in-vxx-x.md 文件中。

8. 在发布日的前一天，将“新特性”分支合并到 main 分支。

9. “新特性”将在“next”文档中上线。当发布分支晋升到 GA (普遍可用) 时，“新特性”也将成为“latest”文档集的一部分。

10. 如何确定内容是否属于“新特性”

Grafana 会在每个次要版本和主要版本发布时，同步发布“新特性”文档页面和博客文章。

这些文章很受欢迎，是用户了解 Grafana 最新精彩功能的好方法。“新特性”也推动了市场赋能：它用于培训销售人员，并制作关于“新特性”主题的视频。

然而，与全面的 CHANGELOG（变更日志）不同，“新特性”是精选的。如果它包含所有更新以及每个小错误修复的详细“新特性”文章，读者阅读起来就会过于嘈杂。

那么，如何决定是否为您的最新改进编写“新特性”文章呢？

为任何可能引起客户兴趣或担忧的内容添加“新特性”条目

“新特性”内容应涉及对用户体验有实质性影响的变更。

包含影响客户的变更，无论是可供尝试的新功能，还是重要且被长期请求的 Bug 修复。

大多数可视化变更和 UI 添加都应包含在“新特性”文档中，即使它们看起来很小。

• 与 Prometheus 和 Loki 相关的几乎所有变更或添加也都是用户关注的重点。
  • “新特性”内容还应包含需要客户采取行动的变更，例如将其 API 密钥更改为服务账户，或停止使用已废弃的 API 或插件。
• “新特性”页面应包含公告——客户需要注意并尝试的内容。这些也可能包括值得注意的社区贡献，以感谢贡献者。
• 如有疑问，请咨询离您最近的产品经理 (PM) 或工程经理 (EM)。倾向于将内容添加到“新特性”中。
• 应包含在“新特性”中的示例

一个新的转换：按值分区。

这是众多转换之一，但它也是一项全新的功能，如果用户不阅读“新特性”文档，可能不会注意到。将内容添加到“新特性”也是一个无需太多精力即可描述该功能的一些良好用例和示例的地方，从而促使用户采用它。

• 新的 K 线图可视化。
  • 这是一个 Beta 功能，但仍列在“新特性”中，以便广而告之并鼓励用户尝试。
• 全新的 API Swagger 文档。
  • 这非常重要，因为它使 Grafana 文档更易于使用，并且是用户在使用 API 时寻求帮助的新途径。
• 移除多个面板的 Beta 标签，使其普遍可用。
  • 这在代码层面是一个小的改变，但对客户影响很大。客户现在知道这些插件已获得全面支持，并推荐在生产环境中使用。
• 新的键盘快捷键
  • 这是一个小的改变，但它引起了人们对最近得到改进且大多数人不知道的功能的关注。
• 火焰图搜索改进
  • 模糊搜索。必须在博客文章中提及。
• Prometheus 查询编辑器变更
  • 这些是大多数用户使用的数据源的查询模式。
• 不应包含在“新特性”中的示例
  • 这些是重要的改进，但最好放在 CHANGELOG 中，而不是“新特性”中

文档更新

此更新无需客户改变其行为。他们下次使用文档时会看到更好的说明。

• 与迁移相关的 Bug 修复
  • 这是一个无需客户操作的 Bug 修复。
• 对现有转换的可用性改进
  • 不错的修复，但非常详细。应该在 CHANGELOG 中，而不是“新特性”中。
• 更改正则表达式以适应 Enterprise 中的新分支策略
  • 此变更对客户不可见。
• “新特性”内容指南
  • 遵循这些指南，确保您的“新特性”或发布说明内容清晰、有用且易于理解。

直接面向您的用户。

使用祈使句或使用“您”来称呼用户。

• 示例：通过抓取面板的查询响应数据和面板设置，缩短向 Grafana Labs 报告问题和请求帮助的沟通时间。

  使用主动语态或现在时态。

  示例：启用一个配置选项，以跳过用户组织和角色与您的安全断言标记语言 (SAML) 提供商的同步。

• 不要提及发布版本，例如，“在 Grafana 9 中，我们”或“截至目前，我们”。

  “新特性”或发布说明旨在提供特定版本的信息，因此无需重复此信息。

• 提供高级别描述。

  告诉客户他们可以使用该功能实现什么目标或解决什么问题。描述商业价值。不要详细说明功能的运作方式或配置步骤。

• 使用段落，而不是项目符号列表。网站使用前两个段落来总结内容，并且不会总结项目符号列表。

  链接到文档中提供更详细信息或步骤的主题。

  示例：通过添加您自己的登录页面、帮助链接、徽标、应用程序名称等，使用自定义品牌将 Grafana 打造成您的可观测性工具。

  不要提及该功能以前的工作方式。

  例如，不要说“以前，当告警规则遇到错误或超时时，其状态会改变。现在，状态不会更新。”

• 对于功能的更改或更新，请提供简短描述。

  您可以使用第一人称复数，例如“我们”。

• 我们的风格通常偏好使用第二人称（“您”），并避免使用第一人称（“我”/“我们”）。发布说明，就像博客文章一样，采用更具对话性的语气，并经常使用第一人称复数：“我们已支持多租户查询。”

• 如果您收到 Vale linter 的错误消息，您可以使用跳过规则来忽略对 Grafana.We 规则的检查。您可以在文件开头的前置元数据之后使用此检查：

  此页面是否有帮助？

  是