跳到主要内容

发布最佳实践

在发布 Grafana 插件时，遵循最佳实践不仅能确保提交和审核流程顺利，还能为用户带来更高质量的体验。通过遵循已建立的指南，您可以提高插件在 Grafana 生态系统中的性能、安全性和可发现性，确保您的插件成为 Grafana 插件的典范。

在继续之前，我们假设您已经创建了您的初始插件，回顾了插件开发最佳实践指南，并熟悉了关于插件签名级别的指导。

本文档概述了您在发布 Grafana 插件之前应遵循的基本最佳实践。这些建议将帮助您避免常见的陷阱，简化审核流程，并创建一个无缝集成到用户工作流程中的插件，同时保持 Grafana 生态系统中期望的高标准。无论您是在微调插件的功能还是准备文档，遵循这些实践都将确保您的插件从一开始就为成功而优化。

填充插件的元数据​

元数据在使您的 Grafana 插件可被发现且用户友好方面起着至关重要的作用。正确构建plugin.json 文件中的元数据不仅可以帮助用户在 Grafana 的插件目录中找到您的插件，还可以提供关于插件功能和兼容性的基本详细信息。

以下是需要重点关注的关键组件的细分

插件名称

name

您的插件名称应清晰、简洁且具有描述性。它是潜在用户的第一个交互点，因此请避免使用过于通用或晦涩难懂的名称。目标是使用能够反映插件主要功能的名称，使其用途一目了然。

描述

info.description

描述字段应简洁地概括您的插件的功能以及用户应安装它的原因。将描述限制为两句话，突出核心功能和用例。写得好的描述不仅能告知用户，还能为目录中更好的搜索结果做出贡献。

关键词

info.keywords

关键词提高了您的插件在 Grafana 目录中的可搜索性。选择准确描述您的插件功能及其支持的数据类型的术语（例如，“JSON”、“SQL”、“可视化”）。

注意

避免关键词堆砌；不相关的关键词将在审核过程中被标记，可能会延迟发布。

徽标

info.logos

添加徽标可以改善您的插件在插件目录中的整体外观和感觉。提供徽标可以增加插件的合法性和专业性。

屏幕截图

info.screenshots

屏幕截图字段应用于提供一个包含一个或多个屏幕截图图像的数组，这些图像将显示在插件目录中。这非常适合向用户提供插件的可视化表示，并可以帮助他们确定此插件是否能解决他们的问题，甚至在安装之前就能确定。请务必提供插件实际运行的屏幕截图，突出显示突出的功能。

注意

确保您的屏幕截图具有合适的分辨率和文件类型（例如 png、jpeg 或 gif）。

Grafana 版本兼容性

dependencies.grafanaDependency

确保您的插件指定了它兼容的最低 Grafana 版本。这保证了运行不同 Grafana 版本的用户知道您的插件是否适用于他们。请务必运行端到端测试，以确认与您支持的版本的兼容性。

创建全面的 README​

您的插件的 README 文件既是用户的初步印象，又是详细指南。将其视为店面广告和使用说明书的结合体——展示您的插件的功能、安装方法以及用户如何在他们的 Grafana 实例中充分利用它。

为了帮助开发者编写高质量的 README，我们提供了一个 README 模板，作为 create-plugin 工具生成的插件结构的一部分。此模板确保您涵盖基本组件，同时让您可以灵活地添加更具体的详细信息。

除了插件的基本概述、用例和要求之外，您还应考虑包含其他元素，以帮助用户理解插件的价值和功能

  • 屏幕截图或屏幕录像： 可视化辅助工具通常比纯文本更能有效地沟通。包括屏幕截图甚至视频演示，使用户可以快速掌握插件的功能和设置过程，让他们有信心有效地使用它。
  • 动态徽章： 徽章提供关于您的插件的快速、一目了然的信息，例如最新发布版本或是否已通过安全和代码检查。诸如 shields.io 之类的工具可以与 Grafana.com API 结合使用，以便在您发布新版本时自动更新这些徽章，从而增加插件的透明度和可信度。
  • 贡献指南： 维护插件可能要求很高，特别是对于个人开发者而言。清楚地概述用户如何提供反馈、报告错误，并将潜在的代码贡献者引导至您的 contributing.md，这些都是帮助促进社区参与的方式，从而更容易长期维护和改进您的插件。

此结构确保您的 README 既信息丰富又引人入胜，为用户提供自信地使用您的插件并为其做出贡献所需的一切。

端到端测试​

端到端 (E2E) 测试确保您的 Grafana 插件在各种环境和受支持的 Grafana 版本中都能正常工作。它通过在类似于最终用户设置的环境中测试插件来复制真实世界的使用情况。实施 E2E 测试有助于在提交前发现问题，从而节省审核过程中的时间并确保更流畅的用户体验。

要点

  • 跨版本测试兼容性： 通过设置针对多个版本的 E2E 测试，确保您的插件与各种 Grafana 版本无缝协作。
  • 自动化测试： 将 E2E 测试集成到您的持续集成 (CI) 管道中，以尽早且频繁地发现问题，减少审核期间的潜在问题。

有关设置 E2E 测试的全面指南，请参阅我们的 插件的 E2E 测试 文档。

验证您的插件​

在提交插件进行审核之前，请验证您的插件，以确保其符合 Grafana 在功能、安全性和结构方面的标准。最简单的方法是使用插件验证器。此工具检查可能阻止您的插件被接受的潜在问题，例如安全漏洞或结构问题。

要点

  • 在本地或 CI 中运行： 您可以在本地运行验证器，或将其集成到您的 CI 工作流程中，以自动化验证过程。请注意，验证器在默认发布工作流程期间自动运行。
  • 验证报告： 该工具生成一份报告，突出显示提交前需要解决的任何错误或警告。

有关使用验证器的更多信息，请参阅 插件验证器文档。

提供已配置的测试环境​

为您的插件配置测试环境可以显著缩短审核时间，并使其他人更容易测试和贡献您的插件。已配置的环境包括预配置的 Grafana 实例，其中包含示例仪表板和数据源，用于演示您的插件的功能。

要点

  • 配置的重要性： 它确保审核人员和贡献者都可以快速验证您的插件的行为，而无需手动设置，从而加快审核和协作过程。
  • 自动化设置： 您可以使用 Docker 配置测试环境，以创建开箱即用的体验，从而复制典型的 Grafana 设置。

要了解有关设置已配置环境的更多信息，请查看我们的配置指南。

使用 GitHub Actions 自动化发布​

为了简化您的插件开发工作流程，最佳实践是使用 GitHub Actions 自动化发布。自动化此过程有助于确保您的插件在每次发布时都正确构建、签名和打包，从而减少人为错误并加快发布过程。

要点

  • 持续集成 (CI)： 使用 GitHub Actions 在每次提交或拉取请求时自动构建和测试您的插件，尽早发现问题。
  • 发布工作流程： 在您准备发布时，自动化插件的签名和打包，确保其满足提交到 Grafana 插件目录的必要标准。

有关详细的设置说明，请参阅我们的 使用 GitHub 自动化打包和签名 指南。

下一步​

通过遵循这些最佳实践——例如仔细填充元数据、创建全面的 README、验证您的插件、配置测试环境以及自动化发布——您可以显著提高插件成功提交的机会。

这些最佳实践中的每一项都旨在确保您的插件不仅通过我们的审核流程，而且还为用户提供卓越的体验。采用这些实践将简化您的工作流程，并帮助创建在 Grafana 生态系统中脱颖而出的插件。

一旦您准备好发布您的插件，请按照我们的提交插件以供审核指南进行操作。我们期待看到您的作品！