跳转到主要内容

发布最佳实践

在发布 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，我们提供了由create-plugin工具生成的插件结构的一部分作为README模板。该模板确保您涵盖基本组件，同时给您添加更多具体细节的灵活性。

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

  • 屏幕截图或屏幕捕获：视觉辅助通常比文字传达得更好。包括截图甚至视频演示可以让用户快速了解插件的功能和设置过程，从而增强他们有效使用它的信心。
  • 动态徽章：徽章可以快速直观地展示有关您插件的信息，例如最新发布版本或是否通过了安全和代码检查。可以使用 shields.io 等工具，结合 Grafana.com API，在您发布新版本时自动更新这些徽章，增加插件的可透明度和可信度。
  • 贡献指南：维护插件可能很费时，尤其是对于个人开发者来说。明确说明用户如何提供反馈、报告错误，并将潜在代码贡献者指引到您的 contributing.md 文件，这些都是帮助培养社区参与、使插件维护和改进更轻松的方法。

这种结构确保您的 README 既有信息性又具有吸引力，为用户提供了一切他们需要的信息，以便自信地使用和贡献您的插件。

端到端测试​

端到端（E2E）测试确保您的 Grafana 插件在各个环境和受支持的 Grafana 版本中都能正确工作。它通过在一个类似于最终用户设置的环境中测试插件来模拟现实世界的使用。实施 E2E 测试有助于在提交前发现问题，节省审查过程中的时间，并确保更流畅的用户体验。

关键点

  • 测试跨版本兼容性：通过设置针对多个版本的 E2E 测试，确保您的插件与 Grafana 的各个版本无缝兼容。
  • 自动化测试：将 E2E 测试集成到您的持续集成（CI）管道中，以尽早频繁地发现问题，减少审查过程中可能的问题。

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

验证您的插件​

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

关键点

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

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

提供预配置的测试环境​

为您的插件预配置测试环境可以显著减少审查时间，并使其他人更容易测试和贡献您的插件。预配置的环境包括具有示例仪表板和数据源的预配置 Grafana 实例，这些仪表板和数据源展示了您插件的功能。

关键点

  • 为什么预配置很重要：它确保审查者和贡献者可以快速验证您插件的行为，而无需手动设置，从而加快审查和协作过程。
  • 自动配置：您可以使用Docker来配置测试环境，创建一个即插即用的体验，以复制典型的Grafana配置。

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

使用GitHub Actions自动化发布​

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

关键点

  • 持续集成（CI）：使用GitHub Actions在每次提交或拉取请求时自动构建和测试您的插件，以便及早发现问题。
  • 发布工作流程：当您准备发布时，自动对插件进行签名和打包，确保它满足提交到Grafana插件目录所需的标准。

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

下一步​

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

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

当您的插件准备发布时，请按照我们的指南提交您的插件进行审查。我们期待看到您的作品！