From 07e2aea87de3db05153b86e5ca5c7af27de7d6eb Mon Sep 17 00:00:00 2001 From: Tom Glenn Date: Mon, 30 Sep 2024 11:28:31 +0100 Subject: [PATCH 01/16] wip --- .../publishing-best-practices.md | 83 +++++++++++++++++++ 1 file changed, 83 insertions(+) create mode 100644 docusaurus/docs/publish-a-plugin/publishing-best-practices.md diff --git a/docusaurus/docs/publish-a-plugin/publishing-best-practices.md b/docusaurus/docs/publish-a-plugin/publishing-best-practices.md new file mode 100644 index 000000000..8bc362674 --- /dev/null +++ b/docusaurus/docs/publish-a-plugin/publishing-best-practices.md @@ -0,0 +1,83 @@ +--- +id: publishing-best-practices +title: Publishing best practices +sidebar_position: 5 +description: Best practices for publishing your plugin +keywords: + - grafana + - plugins + - plugin + - publish + - best practices +--- + +# Publishing best practices + +When publishing a Grafana plugin, adhering to best practices ensures not only a smooth submission and review process but also a higher quality experience for users. By following established guidelines, you improve the plugin’s performance, security, and discoverability within the Grafana ecosystem, ensuring that your plugin stands out as a shining example of what a Grafana plugin can be. + +This document outlines essential best practices for developers to follow before publishing their Grafana plugins. These recommendations will help you avoid common pitfalls, streamline the review process, and create a plugin that integrates seamlessly into users' workflows while maintaining the high standards expected in the Grafana ecosystem. Whether you’re fine-tuning your plugin’s functionality or preparing your documentation, following these practices will ensure that your plugin is optimized for success from the start. + +## Populating your plugin's metadata + +Metadata plays a crucial role in making your Grafana plugin discoverable and user-friendly. Properly structuring the [metadata in your `plugin.json` file](../reference/metadata.md) not only helps users find your plugin in [Grafana’s plugin catalog](https://grafana.com/grafana/plugins/) but also provides essential details about the plugin’s functionality and compatibility. Here’s a breakdown of the key components to focus on: + +**Plugin name (`name`)** + +The name of your plugin should be clear, concise, and descriptive. It is the first point of interaction for potential users, so avoid overly generic or cryptic names. Aim for a name that reflects the plugin’s primary functionality, making it easy to understand its purpose at a glance. + +**Description (`description`)** + +The description field should succinctly summarize what your plugin does and why users should install it. Limit the description to two sentences, highlighting the core functionality and use cases. A well-written description not only informs users but also contributes to better search results in the catalog. + +**Keywords (`keywords`)** + +Keywords improve the searchability of your plugin within Grafana’s catalog. Choose terms that accurately describe your plugin’s functionality and data types it supports (e.g., "JSON", "SQL", "visualization"). However, avoid keyword stuffing; irrelevant keywords will be flagged during the review process, potentially delaying publication. + +**Grafana version compatibility (`grafanaDependency`)** + +Ensure your plugin specifies the minimum Grafana version it is compatible with. This guarantees that users running different versions of Grafana know whether your plugin will work for them. Regularly update this field as new versions of Grafana are released, and [run end-to-end tests](../e2e-test-a-plugin/introduction.md) to confirm compatibility with those releases. + +**Other Grafana plugin dependencies (`plugins`)** + +If your plugin relies on any other published Grafana plugins in order to function correctly, be sure to add them to this array field. Plugins listed as dependencies here will be automatically installed by Grafana when a user installs your plugin. + +--- + +Outline + +2. Build a Comprehensive README + + Core Information: Include plugin overview, usage instructions, and system requirements. + Media Enhancements: Add screenshots or videos to visually guide users through the setup and configuration. + Dynamic Badges: Use dynamic badges to display plugin versions, download stats, and other critical information. + Contribution Guidelines: Provide clear information on how users can contribute, report issues, or offer feedback. + +3. Optimize Metadata for Discoverability + + plugin.json Essentials: Ensure the plugin has a clear name, concise description, and relevant keywords to improve searchability. + Keywords: Use relevant keywords like data types (e.g., JSON) to improve discoverability, but avoid keyword stuffing. + +4. Ensure Compatibility Across Grafana Versions + + Specify grafanaDependency: Declare the minimum supported Grafana version in your plugin.json. + End-to-End Testing: Leverage tools like plugin-e2e to ensure your plugin works seamlessly across different Grafana releases. + +5. Provide a Provisioned Test Environment + + Streamlined Testing: Set up a provisioned environment in Docker for Grafana, including sample dashboards. This speeds up the review process and enables contributors to test the plugin easily. + Improved Collaboration: A provisioned environment allows community members to contribute with more clarity and confidence. + +6. Validate the Plugin + + Use the Validator Tool: Run Grafana’s plugin validator tool locally or in CI to catch any security or structural issues before submission. + Automated CI Workflows: Use GitHub Actions to automate plugin validation during development. + +7. Automate Releases with GitHub Actions + + Continuous Integration: Use GitHub Actions to automate testing and validation on every commit. + Release Workflow: Implement GitHub's release workflows to automate building, signing, and packaging the plugin for submission. + +8. Conclusion + + Recap: Reiterate the importance of following these steps to ensure a smooth plugin review process and enhance user experience. + Additional Resources: Provide links to relevant developer tools and documentation for further reading From 5221d00091206c79ca630ff0371fc6f49c675730 Mon Sep 17 00:00:00 2001 From: Tom Glenn Date: Wed, 2 Oct 2024 14:43:38 +0100 Subject: [PATCH 02/16] Adds a publishing best practices guide --- .../publishing-best-practices.md | 81 ++++++++++++------- 1 file changed, 53 insertions(+), 28 deletions(-) diff --git a/docusaurus/docs/publish-a-plugin/publishing-best-practices.md b/docusaurus/docs/publish-a-plugin/publishing-best-practices.md index 8bc362674..8075bd380 100644 --- a/docusaurus/docs/publish-a-plugin/publishing-best-practices.md +++ b/docusaurus/docs/publish-a-plugin/publishing-best-practices.md @@ -1,7 +1,7 @@ --- id: publishing-best-practices title: Publishing best practices -sidebar_position: 5 +sidebar_position: 0 description: Best practices for publishing your plugin keywords: - grafana @@ -15,11 +15,13 @@ keywords: When publishing a Grafana plugin, adhering to best practices ensures not only a smooth submission and review process but also a higher quality experience for users. By following established guidelines, you improve the plugin’s performance, security, and discoverability within the Grafana ecosystem, ensuring that your plugin stands out as a shining example of what a Grafana plugin can be. -This document outlines essential best practices for developers to follow before publishing their Grafana plugins. These recommendations will help you avoid common pitfalls, streamline the review process, and create a plugin that integrates seamlessly into users' workflows while maintaining the high standards expected in the Grafana ecosystem. Whether you’re fine-tuning your plugin’s functionality or preparing your documentation, following these practices will ensure that your plugin is optimized for success from the start. +This document outlines the essential best practices for you to follow before publishing your Grafana plugin. These recommendations will help you avoid common pitfalls, streamline the review process, and create a plugin that integrates seamlessly into users' workflows while maintaining the high standards expected in the Grafana ecosystem. Whether you’re fine-tuning your plugin’s functionality or preparing your documentation, following these practices will ensure that your plugin is optimized for success from the start. ## Populating your plugin's metadata -Metadata plays a crucial role in making your Grafana plugin discoverable and user-friendly. Properly structuring the [metadata in your `plugin.json` file](../reference/metadata.md) not only helps users find your plugin in [Grafana’s plugin catalog](https://grafana.com/grafana/plugins/) but also provides essential details about the plugin’s functionality and compatibility. Here’s a breakdown of the key components to focus on: +Metadata plays a crucial role in making your Grafana plugin discoverable and user-friendly. Properly structuring the [metadata in your `plugin.json` file](../reference/metadata.md) not only helps users find your plugin in [Grafana’s plugin catalog](https://grafana.com/grafana/plugins/) but also provides essential details about the plugin’s functionality and compatibility. + +Here’s a breakdown of the key components to focus on: **Plugin name (`name`)** @@ -41,43 +43,66 @@ Ensure your plugin specifies the minimum Grafana version it is compatible with. If your plugin relies on any other published Grafana plugins in order to function correctly, be sure to add them to this array field. Plugins listed as dependencies here will be automatically installed by Grafana when a user installs your plugin. ---- +## Creating a comprehensive README + +Your plugin's README file serves as both a first impression and a detailed guide for your users. Think of it as a combination of a storefront advertisement and an instruction manual - showing what your plugin can do, how to install it, and how users can make the most of it within their Grafana instances. + +To assist developers in crafting a high-quality README, we provide a [README template](https://raw.githubusercontent.com/grafana/plugin-tools/main/packages/create-plugin/templates/common/src/README.md) as part of the plugin structure generated by the `create-plugin` tool. This template ensures you cover the essential components while giving you flexibility to add more specific details. + +Beyond a basic overview of your plugin, its use cases, and requirements, there are additional elements you should consider including to help users understand the value and functionality of your plugin: + +- **Screenshots or screen captures:** Visual aids often communicate better than text alone. Including screenshots or even video demonstrations allows users to quickly grasp the plugin’s capabilities and setup process, giving them confidence to use it effectively. +- **Dynamic badges:** Badges provide quick, at-a-glance information about your plugin, such as the latest release version or whether it has passed security and code checks. Tools like [shields.io](https://shields.io/) can be used with the Grafana.com API to automatically update these badges whenever you publish a new version, adding transparency and trustworthiness to your plugin. +- **Contribution guidance:** Maintaining a plugin can be demanding, especially for solo developers. Clearly outlining how users can provide feedback, report bugs, or contribute code improvements helps foster community involvement, making it easier to maintain and improve your plugin over time. + +This structure ensures that your README is both informative and engaging, providing users with everything they need to confidently use and contribute to your plugin. + +## End-to-end testing + +End-to-end (E2E) testing ensures that your Grafana plugin functions correctly across various environments and Grafana versions. It replicates real-world usage by testing the plugin in an environment similar to the end-user's setup. Implementing E2E tests helps catch issues before submission, saving time during the review process and ensuring a smoother user experience. + +**Key points:** + +- **Test compatibility across versions:** Ensure your plugin works seamlessly with various versions of Grafana by setting up E2E tests targeting multiple releases. +- **Automate testing:** Integrate E2E testing into your continuous integration (CI) pipeline to catch issues early and frequently, reducing potential problems during review. + +For a comprehensive guide on setting up E2E tests, see our [E2E test a plugin](../e2e-test-a-plugin/introduction.md) section. + +## Validate your plugin + +Before submitting your plugin for review, you should validate your plugin to ensure that it meets Grafana's standards for functionality, security, and structure. The easiest way to do this is by using the Plugin Validator tool. This tool checks for potential issues that could prevent your plugin from being accepted, such as security vulnerabilities or structural problems. + +**Key points:** -Outline +- **Run locally or in CI:** You can run the validator locally or integrate it into your CI workflow to automate the validation process. +- **Validation reports:** The tool generates a report, highlighting any errors or warnings that need to be addressed before submission. -2. Build a Comprehensive README +For more information on using the validator, refer to the [Plugin Validator documentation](https://github.com/grafana/plugin-validator). - Core Information: Include plugin overview, usage instructions, and system requirements. - Media Enhancements: Add screenshots or videos to visually guide users through the setup and configuration. - Dynamic Badges: Use dynamic badges to display plugin versions, download stats, and other critical information. - Contribution Guidelines: Provide clear information on how users can contribute, report issues, or offer feedback. +## Provide a provisioned test environment -3. Optimize Metadata for Discoverability +Provisioning a test environment for your plugin can significantly reduce the review time and make it easier for others to test and contribute to your plugin. A provisioned environment includes a pre-configured Grafana instance with sample dashboards and data sources that demonstrate your plugin's functionality. - plugin.json Essentials: Ensure the plugin has a clear name, concise description, and relevant keywords to improve searchability. - Keywords: Use relevant keywords like data types (e.g., JSON) to improve discoverability, but avoid keyword stuffing. +**Key points:** -4. Ensure Compatibility Across Grafana Versions +- **Why provisioning matters:** It ensures that both reviewers and contributors can quickly verify your plugin's behaviour without manual setup, speeding up the review and collaboration process. +- **Automated setup:** You can provision test environments using Docker to create an out-of-the-box experience that replicates a typical Grafana setup. - Specify grafanaDependency: Declare the minimum supported Grafana version in your plugin.json. - End-to-End Testing: Leverage tools like plugin-e2e to ensure your plugin works seamlessly across different Grafana releases. +To learn more about setting up provisioned environments, check out our [provisioning guide](../publish-a-plugin/provide-test-environment.md). -5. Provide a Provisioned Test Environment +## Automating releases with GitHub Actions - Streamlined Testing: Set up a provisioned environment in Docker for Grafana, including sample dashboards. This speeds up the review process and enables contributors to test the plugin easily. - Improved Collaboration: A provisioned environment allows community members to contribute with more clarity and confidence. +To streamline your plugin development workflow, it's a best practice to automate releases using GitHub Actions. Automating this process helps ensure that your plugin is built, signed, and packaged correctly on each release, reducing human error and expediting the publishing process. -6. Validate the Plugin +**Key points:** - Use the Validator Tool: Run Grafana’s plugin validator tool locally or in CI to catch any security or structural issues before submission. - Automated CI Workflows: Use GitHub Actions to automate plugin validation during development. +- **Continuous integration (CI):** Use GitHub Actions to automatically build and test your plugin on every commit or pull request, catching issues early. +- **Release workflow:** Automate the signing and packaging of your plugin when you're ready to publish, ensuring it meets the necessary criteria for submission to the Grafana plugin catalog. -7. Automate Releases with GitHub Actions +For detailed setup instructions, refer to our [Automate packaging and signing with GitHub](../publish-a-plugin/build-automation.md) guide. - Continuous Integration: Use GitHub Actions to automate testing and validation on every commit. - Release Workflow: Implement GitHub's release workflows to automate building, signing, and packaging the plugin for submission. +## Next steps -8. Conclusion +By following these best practices - such as carefully populating metadata, creating a comprehensive README, validating your plugin, provisioning test environments, and automating releases - you significantly increase the chances of a successful plugin submission. Each step is designed to ensure that your plugin not only passes our review process but also delivers an exceptional experience for users. Adopting these practices will streamline your workflow and help create plugins that stand out in the Grafana ecosystem. - Recap: Reiterate the importance of following these steps to ensure a smooth plugin review process and enhance user experience. - Additional Resources: Provide links to relevant developer tools and documentation for further reading +Once your ready for your plugin to be published, head on over to Grafana Cloud and follow our guide for [submitting your plugin for review](../publish-a-plugin/publish-or-update-a-plugin.md) - we look forward to seeing what you create! From 2cfcc07630f57568b5b7dfa8ab91aafd52e926d8 Mon Sep 17 00:00:00 2001 From: Tom Glenn Date: Fri, 4 Oct 2024 10:18:46 +0100 Subject: [PATCH 03/16] Add link to publishing best practices in publish guide --- docusaurus/docs/publish-a-plugin/publish-or-update-a-plugin.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docusaurus/docs/publish-a-plugin/publish-or-update-a-plugin.md b/docusaurus/docs/publish-a-plugin/publish-or-update-a-plugin.md index 0b8987685..10a06df5f 100644 --- a/docusaurus/docs/publish-a-plugin/publish-or-update-a-plugin.md +++ b/docusaurus/docs/publish-a-plugin/publish-or-update-a-plugin.md @@ -21,6 +21,7 @@ In this guide you learn how to manage the lifecycle of a plugin in the catalog, ## Before you begin - [Review our guidelines](https://grafana.com/legal/plugins/#plugin-publishing-and-signing-criteria) - Learn about the Grafana Labs criteria for publishing and signing plugins. +- [Review our publishing best practices](../publish-a-plugin/publishing-best-practices.md) - Ensure your plugin is in the best state it can be before submitting it for review. - [Package a plugin](./package-a-plugin.md) - Build the plugin and get it ready to share in the form of a ZIP archive. - Refer to [plugin-examples](https://github.com/grafana/grafana-plugin-examples) to review best practices for building your plugin. From 8f329a9aa46a76583d74ad4b45a74f5dea651846 Mon Sep 17 00:00:00 2001 From: Tom Glenn Date: Fri, 4 Oct 2024 10:32:24 +0100 Subject: [PATCH 04/16] Clarify external plugins only --- docusaurus/docs/publish-a-plugin/publishing-best-practices.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docusaurus/docs/publish-a-plugin/publishing-best-practices.md b/docusaurus/docs/publish-a-plugin/publishing-best-practices.md index 8075bd380..3ad0aa311 100644 --- a/docusaurus/docs/publish-a-plugin/publishing-best-practices.md +++ b/docusaurus/docs/publish-a-plugin/publishing-best-practices.md @@ -41,7 +41,7 @@ Ensure your plugin specifies the minimum Grafana version it is compatible with. **Other Grafana plugin dependencies (`plugins`)** -If your plugin relies on any other published Grafana plugins in order to function correctly, be sure to add them to this array field. Plugins listed as dependencies here will be automatically installed by Grafana when a user installs your plugin. +If your plugin relies on any other external Grafana plugins (i.e. non-core plugins) in order to function correctly, be sure to add them to this array field. Plugins listed as dependencies here will be automatically installed by Grafana when a user installs your plugin. ## Creating a comprehensive README From 04fe88cd66fd5287369880a4d35409e249c5a5aa Mon Sep 17 00:00:00 2001 From: Tom Glenn Date: Mon, 7 Oct 2024 10:28:49 +0100 Subject: [PATCH 05/16] Tweaks RE feedback --- .../publishing-best-practices.md | 30 ++++++++++++++----- 1 file changed, 23 insertions(+), 7 deletions(-) diff --git a/docusaurus/docs/publish-a-plugin/publishing-best-practices.md b/docusaurus/docs/publish-a-plugin/publishing-best-practices.md index 3ad0aa311..fd647c70b 100644 --- a/docusaurus/docs/publish-a-plugin/publishing-best-practices.md +++ b/docusaurus/docs/publish-a-plugin/publishing-best-practices.md @@ -23,25 +23,41 @@ Metadata plays a crucial role in making your Grafana plugin discoverable and use Here’s a breakdown of the key components to focus on: -**Plugin name (`name`)** +**[Plugin name](../reference/plugin-json#properties)** + +`name` The name of your plugin should be clear, concise, and descriptive. It is the first point of interaction for potential users, so avoid overly generic or cryptic names. Aim for a name that reflects the plugin’s primary functionality, making it easy to understand its purpose at a glance. -**Description (`description`)** +**[Description](../reference/plugin-json#info)** + +`info.description` The description field should succinctly summarize what your plugin does and why users should install it. Limit the description to two sentences, highlighting the core functionality and use cases. A well-written description not only informs users but also contributes to better search results in the catalog. -**Keywords (`keywords`)** +**[Keywords](../reference/plugin-json#info)** + +`info.keywords` Keywords improve the searchability of your plugin within Grafana’s catalog. Choose terms that accurately describe your plugin’s functionality and data types it supports (e.g., "JSON", "SQL", "visualization"). However, avoid keyword stuffing; irrelevant keywords will be flagged during the review process, potentially delaying publication. -**Grafana version compatibility (`grafanaDependency`)** +**[Logos](../reference/plugin-json#info)** + +`info.logos` + +Adding logos improves the overall look and feel of your plugin within the plugin catalog. Providing a logo adds legitimacy and professionalism to your plugin. + +**[Screenshots](../reference/plugin-json#info)** + +`info.screenshots` + +The screenshots field should be used to provide an array of screenshot images that will be displayed within the plugin catalog. This is great for providing users with a visual representation of your plugin and can help them establish whether or not this plugin solves their problem before they even install it. Be sure to provide screenshots of your plugin in action, highlighting the standout features. -Ensure your plugin specifies the minimum Grafana version it is compatible with. This guarantees that users running different versions of Grafana know whether your plugin will work for them. Regularly update this field as new versions of Grafana are released, and [run end-to-end tests](../e2e-test-a-plugin/introduction.md) to confirm compatibility with those releases. +**[Grafana version compatibility](../reference/plugin-json#dependencies)** -**Other Grafana plugin dependencies (`plugins`)** +`dependencies.grafanaDependency` -If your plugin relies on any other external Grafana plugins (i.e. non-core plugins) in order to function correctly, be sure to add them to this array field. Plugins listed as dependencies here will be automatically installed by Grafana when a user installs your plugin. +Ensure your plugin specifies the minimum Grafana version it is compatible with. This guarantees that users running different versions of Grafana know whether your plugin will work for them. Be sure to [run end-to-end tests](../e2e-test-a-plugin/introduction.md) to confirm compatibility with releases you support. ## Creating a comprehensive README From e709f22484243d99b5363acb03bf1629cbf41b7d Mon Sep 17 00:00:00 2001 From: Tom Glenn <289945+tomglenn@users.noreply.github.com> Date: Mon, 7 Oct 2024 10:29:11 +0100 Subject: [PATCH 06/16] Update docusaurus/docs/publish-a-plugin/publishing-best-practices.md Co-authored-by: David Harris --- docusaurus/docs/publish-a-plugin/publishing-best-practices.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docusaurus/docs/publish-a-plugin/publishing-best-practices.md b/docusaurus/docs/publish-a-plugin/publishing-best-practices.md index fd647c70b..48d48e94c 100644 --- a/docusaurus/docs/publish-a-plugin/publishing-best-practices.md +++ b/docusaurus/docs/publish-a-plugin/publishing-best-practices.md @@ -33,7 +33,7 @@ The name of your plugin should be clear, concise, and descriptive. It is the fir `info.description` -The description field should succinctly summarize what your plugin does and why users should install it. Limit the description to two sentences, highlighting the core functionality and use cases. A well-written description not only informs users but also contributes to better search results in the catalog. +The description field should succinctly summarize what your plugin does and why users should install it. Limit the description to two sentences, highlighting the core functionality and use cases. A well-written description not only informs users, but also contributes to better search results in the catalog. **[Keywords](../reference/plugin-json#info)** From e03117630fcb55dc966895436d1c3ca33d56e424 Mon Sep 17 00:00:00 2001 From: Tom Glenn Date: Mon, 7 Oct 2024 10:38:38 +0100 Subject: [PATCH 07/16] Further tweaks --- .../docs/publish-a-plugin/publishing-best-practices.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docusaurus/docs/publish-a-plugin/publishing-best-practices.md b/docusaurus/docs/publish-a-plugin/publishing-best-practices.md index 48d48e94c..265d5b5a6 100644 --- a/docusaurus/docs/publish-a-plugin/publishing-best-practices.md +++ b/docusaurus/docs/publish-a-plugin/publishing-best-practices.md @@ -13,7 +13,9 @@ keywords: # Publishing best practices -When publishing a Grafana plugin, adhering to best practices ensures not only a smooth submission and review process but also a higher quality experience for users. By following established guidelines, you improve the plugin’s performance, security, and discoverability within the Grafana ecosystem, ensuring that your plugin stands out as a shining example of what a Grafana plugin can be. +When publishing a Grafana plugin, following best practices ensures not only a smooth submission and review process but also a higher quality experience for users. By following established guidelines, you improve the plugin’s performance, security, and discoverability within the Grafana ecosystem, ensuring that your plugin stands out as a shining example of what a Grafana plugin can be. + +Before proceeding, we assume that you've already [created your initial plugin](../), reviewed the [best practices for plugin development guide](../get-started/best-practices), and familiarized yourself with the guidance on [plugin signature levels](../publish-a-plugin/sign-a-plugin#public-or-private-plugins). This document outlines the essential best practices for you to follow before publishing your Grafana plugin. These recommendations will help you avoid common pitfalls, streamline the review process, and create a plugin that integrates seamlessly into users' workflows while maintaining the high standards expected in the Grafana ecosystem. Whether you’re fine-tuning your plugin’s functionality or preparing your documentation, following these practices will ensure that your plugin is optimized for success from the start. @@ -90,7 +92,7 @@ Before submitting your plugin for review, you should validate your plugin to ens **Key points:** -- **Run locally or in CI:** You can run the validator locally or integrate it into your CI workflow to automate the validation process. +- **Run locally or in CI:** You can run the validator locally or integrate it into your CI workflow to automate the validation process. Note, the validator runs automatically during the default release workflow. - **Validation reports:** The tool generates a report, highlighting any errors or warnings that need to be addressed before submission. For more information on using the validator, refer to the [Plugin Validator documentation](https://github.com/grafana/plugin-validator). From d3e0f19c7d428346870c3b0ea86f78c3c879332b Mon Sep 17 00:00:00 2001 From: Tom Glenn <289945+tomglenn@users.noreply.github.com> Date: Tue, 8 Oct 2024 11:14:52 +0100 Subject: [PATCH 08/16] Update docusaurus/docs/publish-a-plugin/publishing-best-practices.md Co-authored-by: Usman Ahmad --- docusaurus/docs/publish-a-plugin/publishing-best-practices.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docusaurus/docs/publish-a-plugin/publishing-best-practices.md b/docusaurus/docs/publish-a-plugin/publishing-best-practices.md index 265d5b5a6..4d421b64d 100644 --- a/docusaurus/docs/publish-a-plugin/publishing-best-practices.md +++ b/docusaurus/docs/publish-a-plugin/publishing-best-practices.md @@ -77,7 +77,7 @@ This structure ensures that your README is both informative and engaging, provid ## End-to-end testing -End-to-end (E2E) testing ensures that your Grafana plugin functions correctly across various environments and Grafana versions. It replicates real-world usage by testing the plugin in an environment similar to the end-user's setup. Implementing E2E tests helps catch issues before submission, saving time during the review process and ensuring a smoother user experience. +End-to-end (E2E) testing ensures that your Grafana plugin works correctly across various environments and supported Grafana versions. It replicates real-world usage by testing the plugin in an environment similar to the end-user's setup. Implementing E2E tests helps catch issues before submission, saving time during the review process and ensuring a smoother user experience. **Key points:** From f6b1e5d5469571a8820fb94291def0c895aae917 Mon Sep 17 00:00:00 2001 From: Tom Glenn Date: Tue, 8 Oct 2024 12:19:25 +0100 Subject: [PATCH 09/16] feedback tweaks --- .../publishing-best-practices.md | 20 ++++++++++++++++--- 1 file changed, 17 insertions(+), 3 deletions(-) diff --git a/docusaurus/docs/publish-a-plugin/publishing-best-practices.md b/docusaurus/docs/publish-a-plugin/publishing-best-practices.md index 4d421b64d..68f9ff70c 100644 --- a/docusaurus/docs/publish-a-plugin/publishing-best-practices.md +++ b/docusaurus/docs/publish-a-plugin/publishing-best-practices.md @@ -41,7 +41,13 @@ The description field should succinctly summarize what your plugin does and why `info.keywords` -Keywords improve the searchability of your plugin within Grafana’s catalog. Choose terms that accurately describe your plugin’s functionality and data types it supports (e.g., "JSON", "SQL", "visualization"). However, avoid keyword stuffing; irrelevant keywords will be flagged during the review process, potentially delaying publication. +Keywords improve the searchability of your plugin within Grafana’s catalog. Choose terms that accurately describe your plugin’s functionality and data types it supports (e.g., "JSON", "SQL", "visualization"). + +:::note + +Avoid keyword stuffing; irrelevant keywords will be flagged during the review process, potentially delaying publication. + +::: **[Logos](../reference/plugin-json#info)** @@ -55,6 +61,12 @@ Adding logos improves the overall look and feel of your plugin within the plugin The screenshots field should be used to provide an array of screenshot images that will be displayed within the plugin catalog. This is great for providing users with a visual representation of your plugin and can help them establish whether or not this plugin solves their problem before they even install it. Be sure to provide screenshots of your plugin in action, highlighting the standout features. +:::note + +Ensure your screenshots are a suitable resolution and file type (e.g. png, jpeg, or gif). + +::: + **[Grafana version compatibility](../reference/plugin-json#dependencies)** `dependencies.grafanaDependency` @@ -71,7 +83,7 @@ Beyond a basic overview of your plugin, its use cases, and requirements, there a - **Screenshots or screen captures:** Visual aids often communicate better than text alone. Including screenshots or even video demonstrations allows users to quickly grasp the plugin’s capabilities and setup process, giving them confidence to use it effectively. - **Dynamic badges:** Badges provide quick, at-a-glance information about your plugin, such as the latest release version or whether it has passed security and code checks. Tools like [shields.io](https://shields.io/) can be used with the Grafana.com API to automatically update these badges whenever you publish a new version, adding transparency and trustworthiness to your plugin. -- **Contribution guidance:** Maintaining a plugin can be demanding, especially for solo developers. Clearly outlining how users can provide feedback, report bugs, or contribute code improvements helps foster community involvement, making it easier to maintain and improve your plugin over time. +- **Contribution guidance:** Maintaining a plugin can be demanding, especially for individual developers. Clearly outlining how users can provide feedback, report bugs, or contribute code improvements helps foster community involvement, making it easier to maintain and improve your plugin over time. This structure ensures that your README is both informative and engaging, providing users with everything they need to confidently use and contribute to your plugin. @@ -121,6 +133,8 @@ For detailed setup instructions, refer to our [Automate packaging and signing wi ## Next steps -By following these best practices - such as carefully populating metadata, creating a comprehensive README, validating your plugin, provisioning test environments, and automating releases - you significantly increase the chances of a successful plugin submission. Each step is designed to ensure that your plugin not only passes our review process but also delivers an exceptional experience for users. Adopting these practices will streamline your workflow and help create plugins that stand out in the Grafana ecosystem. +By following these best practices - such as carefully populating metadata, creating a comprehensive README, validating your plugin, provisioning test environments, and automating releases - you significantly increase the chances of a successful plugin submission. + +Each of these best practices are designed to ensure that your plugin not only passes our review process but also delivers an exceptional experience for users. Adopting these practices will streamline your workflow and help create plugins that stand out in the Grafana ecosystem. Once your ready for your plugin to be published, head on over to Grafana Cloud and follow our guide for [submitting your plugin for review](../publish-a-plugin/publish-or-update-a-plugin.md) - we look forward to seeing what you create! From cf2b34d76e3ab6d754b6ab897fc4cb4fbb83db62 Mon Sep 17 00:00:00 2001 From: Tom Glenn Date: Tue, 8 Oct 2024 12:20:30 +0100 Subject: [PATCH 10/16] Add grafana cloud link --- docusaurus/docs/publish-a-plugin/publishing-best-practices.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docusaurus/docs/publish-a-plugin/publishing-best-practices.md b/docusaurus/docs/publish-a-plugin/publishing-best-practices.md index 68f9ff70c..42657808f 100644 --- a/docusaurus/docs/publish-a-plugin/publishing-best-practices.md +++ b/docusaurus/docs/publish-a-plugin/publishing-best-practices.md @@ -137,4 +137,4 @@ By following these best practices - such as carefully populating metadata, creat Each of these best practices are designed to ensure that your plugin not only passes our review process but also delivers an exceptional experience for users. Adopting these practices will streamline your workflow and help create plugins that stand out in the Grafana ecosystem. -Once your ready for your plugin to be published, head on over to Grafana Cloud and follow our guide for [submitting your plugin for review](../publish-a-plugin/publish-or-update-a-plugin.md) - we look forward to seeing what you create! +Once your ready for your plugin to be published, head on over to [Grafana Cloud](https://grafana.com/get/) and follow our guide for [submitting your plugin for review](../publish-a-plugin/publish-or-update-a-plugin.md) - we look forward to seeing what you create! From 0aa16cd7d0c1e8398b337225b7b4fc73008a7b34 Mon Sep 17 00:00:00 2001 From: Tom Glenn <289945+tomglenn@users.noreply.github.com> Date: Fri, 11 Oct 2024 14:25:01 +0100 Subject: [PATCH 11/16] Update docusaurus/docs/publish-a-plugin/publishing-best-practices.md Co-authored-by: David Harris --- docusaurus/docs/publish-a-plugin/publishing-best-practices.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docusaurus/docs/publish-a-plugin/publishing-best-practices.md b/docusaurus/docs/publish-a-plugin/publishing-best-practices.md index 42657808f..b585c54ac 100644 --- a/docusaurus/docs/publish-a-plugin/publishing-best-practices.md +++ b/docusaurus/docs/publish-a-plugin/publishing-best-practices.md @@ -59,7 +59,7 @@ Adding logos improves the overall look and feel of your plugin within the plugin `info.screenshots` -The screenshots field should be used to provide an array of screenshot images that will be displayed within the plugin catalog. This is great for providing users with a visual representation of your plugin and can help them establish whether or not this plugin solves their problem before they even install it. Be sure to provide screenshots of your plugin in action, highlighting the standout features. +The screenshots field should be used to provide an array with one or more screenshot images that will be displayed within the plugin catalog. This is great for providing users with a visual representation of your plugin and can help them establish whether or not this plugin solves their problem before they even install it. Be sure to provide screenshots of your plugin in action, highlighting the standout features. :::note From 980f45373d78a4852ad362d2d0da758de9744bf0 Mon Sep 17 00:00:00 2001 From: Tom Glenn <289945+tomglenn@users.noreply.github.com> Date: Fri, 11 Oct 2024 14:25:23 +0100 Subject: [PATCH 12/16] Update docusaurus/docs/publish-a-plugin/publishing-best-practices.md Co-authored-by: Joseph Perez <45749060+josmperez@users.noreply.github.com> --- docusaurus/docs/publish-a-plugin/publishing-best-practices.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docusaurus/docs/publish-a-plugin/publishing-best-practices.md b/docusaurus/docs/publish-a-plugin/publishing-best-practices.md index b585c54ac..a76670ded 100644 --- a/docusaurus/docs/publish-a-plugin/publishing-best-practices.md +++ b/docusaurus/docs/publish-a-plugin/publishing-best-practices.md @@ -96,7 +96,7 @@ End-to-end (E2E) testing ensures that your Grafana plugin works correctly across - **Test compatibility across versions:** Ensure your plugin works seamlessly with various versions of Grafana by setting up E2E tests targeting multiple releases. - **Automate testing:** Integrate E2E testing into your continuous integration (CI) pipeline to catch issues early and frequently, reducing potential problems during review. -For a comprehensive guide on setting up E2E tests, see our [E2E test a plugin](../e2e-test-a-plugin/introduction.md) section. +For a comprehensive guide on setting up E2E tests, refer to our [E2E test a plugin](../e2e-test-a-plugin/introduction.md) documentation. ## Validate your plugin From ae90ea5c4fa0e2ddb6375a8a25e2dd0ff0bf815e Mon Sep 17 00:00:00 2001 From: Tom Glenn <289945+tomglenn@users.noreply.github.com> Date: Fri, 11 Oct 2024 14:26:23 +0100 Subject: [PATCH 13/16] Update docusaurus/docs/publish-a-plugin/publishing-best-practices.md Co-authored-by: Joseph Perez <45749060+josmperez@users.noreply.github.com> --- docusaurus/docs/publish-a-plugin/publishing-best-practices.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docusaurus/docs/publish-a-plugin/publishing-best-practices.md b/docusaurus/docs/publish-a-plugin/publishing-best-practices.md index a76670ded..160bca0b6 100644 --- a/docusaurus/docs/publish-a-plugin/publishing-best-practices.md +++ b/docusaurus/docs/publish-a-plugin/publishing-best-practices.md @@ -100,7 +100,7 @@ For a comprehensive guide on setting up E2E tests, refer to our [E2E test a plug ## Validate your plugin -Before submitting your plugin for review, you should validate your plugin to ensure that it meets Grafana's standards for functionality, security, and structure. The easiest way to do this is by using the Plugin Validator tool. This tool checks for potential issues that could prevent your plugin from being accepted, such as security vulnerabilities or structural problems. +Before submitting your plugin for review, validate your plugin to ensure that it meets Grafana's standards for functionality, security, and structure. The easiest way to do this is with the Plugin Validator. This tool checks for potential issues that could prevent your plugin from being accepted, such as security vulnerabilities or structural problems. **Key points:** From c1375122add4b9884b802a0f0377d9083af12f36 Mon Sep 17 00:00:00 2001 From: Tom Glenn <289945+tomglenn@users.noreply.github.com> Date: Fri, 11 Oct 2024 14:29:24 +0100 Subject: [PATCH 14/16] Update docusaurus/docs/publish-a-plugin/publishing-best-practices.md Co-authored-by: Joseph Perez <45749060+josmperez@users.noreply.github.com> --- docusaurus/docs/publish-a-plugin/publishing-best-practices.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docusaurus/docs/publish-a-plugin/publishing-best-practices.md b/docusaurus/docs/publish-a-plugin/publishing-best-practices.md index 160bca0b6..2aebcd6a9 100644 --- a/docusaurus/docs/publish-a-plugin/publishing-best-practices.md +++ b/docusaurus/docs/publish-a-plugin/publishing-best-practices.md @@ -137,4 +137,4 @@ By following these best practices - such as carefully populating metadata, creat Each of these best practices are designed to ensure that your plugin not only passes our review process but also delivers an exceptional experience for users. Adopting these practices will streamline your workflow and help create plugins that stand out in the Grafana ecosystem. -Once your ready for your plugin to be published, head on over to [Grafana Cloud](https://grafana.com/get/) and follow our guide for [submitting your plugin for review](../publish-a-plugin/publish-or-update-a-plugin.md) - we look forward to seeing what you create! +Once you're ready for your plugin to be published, follow our guide for [submitting your plugin for review](../publish-a-plugin/publish-or-update-a-plugin.md). We look forward to seeing what you create! From fff10a20fbfb7e8e44124e071d3d9bb7e6753632 Mon Sep 17 00:00:00 2001 From: Tom Glenn <289945+tomglenn@users.noreply.github.com> Date: Fri, 11 Oct 2024 14:46:11 +0100 Subject: [PATCH 15/16] Update docusaurus/docs/publish-a-plugin/publishing-best-practices.md Co-authored-by: Joseph Perez <45749060+josmperez@users.noreply.github.com> --- docusaurus/docs/publish-a-plugin/publishing-best-practices.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docusaurus/docs/publish-a-plugin/publishing-best-practices.md b/docusaurus/docs/publish-a-plugin/publishing-best-practices.md index 2aebcd6a9..4d9612504 100644 --- a/docusaurus/docs/publish-a-plugin/publishing-best-practices.md +++ b/docusaurus/docs/publish-a-plugin/publishing-best-practices.md @@ -75,7 +75,7 @@ Ensure your plugin specifies the minimum Grafana version it is compatible with. ## Creating a comprehensive README -Your plugin's README file serves as both a first impression and a detailed guide for your users. Think of it as a combination of a storefront advertisement and an instruction manual - showing what your plugin can do, how to install it, and how users can make the most of it within their Grafana instances. +Your plugin's README file serves as both a first impression and a detailed guide for your users. Think of it as a combination of a storefront advertisement and an instruction manual—showing what your plugin can do, how to install it, and how users can make the most of it within their Grafana instances. To assist developers in crafting a high-quality README, we provide a [README template](https://raw.githubusercontent.com/grafana/plugin-tools/main/packages/create-plugin/templates/common/src/README.md) as part of the plugin structure generated by the `create-plugin` tool. This template ensures you cover the essential components while giving you flexibility to add more specific details. From f2e0a5ab89c752eb031ef9f1f74e8b6ab0e9f2d3 Mon Sep 17 00:00:00 2001 From: Tom Glenn Date: Fri, 11 Oct 2024 14:47:17 +0100 Subject: [PATCH 16/16] Tweak contributing guidance --- docusaurus/docs/publish-a-plugin/publishing-best-practices.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docusaurus/docs/publish-a-plugin/publishing-best-practices.md b/docusaurus/docs/publish-a-plugin/publishing-best-practices.md index 4d9612504..8b0b4b9ec 100644 --- a/docusaurus/docs/publish-a-plugin/publishing-best-practices.md +++ b/docusaurus/docs/publish-a-plugin/publishing-best-practices.md @@ -83,7 +83,7 @@ Beyond a basic overview of your plugin, its use cases, and requirements, there a - **Screenshots or screen captures:** Visual aids often communicate better than text alone. Including screenshots or even video demonstrations allows users to quickly grasp the plugin’s capabilities and setup process, giving them confidence to use it effectively. - **Dynamic badges:** Badges provide quick, at-a-glance information about your plugin, such as the latest release version or whether it has passed security and code checks. Tools like [shields.io](https://shields.io/) can be used with the Grafana.com API to automatically update these badges whenever you publish a new version, adding transparency and trustworthiness to your plugin. -- **Contribution guidance:** Maintaining a plugin can be demanding, especially for individual developers. Clearly outlining how users can provide feedback, report bugs, or contribute code improvements helps foster community involvement, making it easier to maintain and improve your plugin over time. +- **Contribution guidance:** Maintaining a plugin can be demanding, especially for individual developers. Clearly outlining how users can provide feedback, report bugs, and directing potential code contributors to your `contributing.md` are all ways to help foster community involvement, making it easier to maintain and improve your plugin over time. This structure ensures that your README is both informative and engaging, providing users with everything they need to confidently use and contribute to your plugin.