Docs: Publish a plugin landing (#2028)

Author: urbiz-grafana

docusaurus/docs/publish-a-plugin/build-automation.md

@@ -20,7 +20,7 @@ to ensure that your plugin will be built and packaged in the correct format.
 
 Additionally, we recommend using the zip file produced from this workflow to test the plugin.
 
-If a Grafana Access Policy Token is included in your [Github repository secrets](https://docs.github.com/en/codespaces/managing-codespaces-for-your-organization/managing-development-environment-secrets-for-your-repository-or-organization), a signed build is automatically created, which you can use to test the plugin locally before submission. The [sign a plugin](./sign-a-plugin.md#generate-an-access-policy-token) documentation includes guidance on how to create this token.
+If you include a Grafana Access Policy Token in your [Github repository secrets](https://docs.github.com/en/codespaces/managing-codespaces-for-your-organization/managing-development-environment-secrets-for-your-repository-or-organization), a signed build is automatically created, and you can use it to test the plugin locally before submission. The [sign a plugin](./sign-a-plugin.md#generate-an-access-policy-token) documentation includes guidance on how to create this token.
 
 By creating a release tag, the whole process becomes automated, resulting in a zip file that you can submit for publication to the [Grafana plugin catalog](https://grafana.com/plugins)
 
@@ -93,7 +93,7 @@ After creating the tag, push it to the repository:
 git push origin main --follow-tags
 ```
 
-## Publish your release in Github
+## Publish your release in GitHub
 
 After you [create and push the tag](#how-to-trigger-the-release-workflow), the release workflow will run, generating a release with all the artifacts needed to submit your plugin to the [Grafana plugin catalog](https://grafana.com/plugins).
 
@@ -107,13 +107,13 @@ Once the draft release is published, you can use the release assets to submit yo
 
 Access the release zip file directly from the GitHub repository release path (for example, `https://github.com/org/plugin-id/releases`).
 
-## Signing your plugin automatically
+## Sign your plugin automatically
 
-You can sign your plugin releases using the Github Action. First you will have to [Generate an Access Policy Token](./sign-a-plugin.md#generate-an-access-policy-token) and [save it in your repository secrets](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-a-repository).
+You can sign your plugin releases using GitHub Action. 
 
-Save your Access Policy Token as `GRAFANA_ACCESS_POLICY_TOKEN`.
+First, [generate an Access Policy Token](./sign-a-plugin.md#generate-an-access-policy-token) and [save it in your repository secrets](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-a-repository) as `GRAFANA_ACCESS_POLICY_TOKEN`.
 
-By default, create-plugin will add the following `release.yml` to your scaffolded plugin with the following contents. If this is missing from your plugin repository, copy the following to add the workflow:
+By default, create-plugin adds the following `release.yml` to your scaffolded plugin with the following contents. If this is missing from your plugin repository, copy the following to add the workflow:
 
 ```yaml title=".github/workflows/release.yml"
 name: Release
@@ -142,11 +142,11 @@ jobs:
           use_changelog_generator: true # Enable automatic changelog generation
 ```
 
-Then, follow the regular process to [trigger](#how-to-trigger-the-release-workflow) the release workflow. Your plugin will be signed automatically, and you can use the release assets for your plugin submission.
+Next, follow the regular process to [trigger](#how-to-trigger-the-release-workflow) the release workflow. Your plugin will be signed automatically, and you can use the release assets for your plugin submission.
 
-## Provenance attestation for plugin builds
+## Attest provenance for plugin builds
 
-Provenance attestation, that is, _a feature that generating verifiable records of the build's origin and process_, enhances the security of your plugin builds. This feature allows users to confirm that the plugin they are installing was created through your official build pipeline.
+Provenance attestation is a feature that generates verifiable records of the build's origin and process, enhancing the security of your plugin builds. With this feature users can confirm that the plugin they're installing was created through your official build pipeline.
 
 Currently, this feature is available only with GitHub Actions in public repositories. While we recommend using GitHub Actions with provenance attestation for improved security, you can still build and distribute plugins using other CI/CD platforms or manual methods.
 
@@ -172,7 +172,7 @@ permissions:
     attestation: true
 ```
 
-The workflow will generate attestations automatically when building your plugin zip file.
+The workflow generates attestations automatically when building your plugin zip file.
 
 ### Troubleshoot provenance attestation
 
@@ -183,11 +183,11 @@ If you encounter errors in the plugin validator or your plugin submission like t
 
 Follow the steps above to enable provenance attestation in your GitHub Actions workflow.
 
-## Automatically Generate Changelogs
+## Generate changelogs automatically 
 
 Maintaining a detailed changelog is essential for communicating updates to your users and is displayed prominently in the Grafana plugin details page. To simplify this process, our plugin build workflow supports automatic changelog generation.
 
-### Using the GitHub Actions Workflow for Changelog Generation
+### Use the GitHub Actions workflow to generate changelog
 
 The build-plugin GitHub Action can automatically generate and maintain your plugin's changelog using the [github-changelog-generator](https://github.com/github-changelog-generator/github-changelog-generator) tool. This feature:
 
@@ -216,7 +216,7 @@ permissions:
   contents: write
 ```
 
-The changelog generator requires write access to commit the updated CHANGELOG.md file to your repository.
+The changelog generator requires write access to commit the updated `CHANGELOG.md` file to your repository.
 
 If your target branch is protected, the default github.token cannot push changes directly, even with write permissions. In this case, you need to:
 
@@ -232,7 +232,7 @@ If your target branch is protected, the default github.token cannot push changes
     token: ${{ secrets.CHANGELOG_PAT }} # Replace default github.token
 ```
 
-### Generated Changelog Format
+### Generated changelog format
 
 The generated changelog follows a standardized format that clearly categorizes changes:
 
@@ -260,4 +260,4 @@ The generated changelog follows a standardized format that clearly categorizes c
 
 ## Next steps
 
-When you've packaged your plugin, proceed to [publishing a plugin](./publish-or-update-a-plugin.md) or [installing a packaged plugin](https://grafana.com/docs/grafana/latest/administration/plugin-management/#install-a-packaged-plugin).
+After you've packaged your plugin, proceed to [publish a plugin](./publish-or-update-a-plugin.md) or [install a packaged plugin](https://grafana.com/docs/grafana/latest/administration/plugin-management/#install-a-packaged-plugin).

docusaurus/docs/publish-a-plugin/index.md

@@ -0,0 +1,14 @@
+---
+id: publish-plugin-intro
+title: Publish your plugins 
+description: Learn how to publish your Grafana plugins.
+keywords:
+  - grafana
+  - plugins
+  - plugin
+  - publish
+---
+
+See the following docs to learn how to publish your Grafana plugin.
+
+<DocLinkList />

docusaurus/docs/publish-a-plugin/provide-test-environment.md

@@ -12,13 +12,19 @@ sidebar_position: 5
 
 # Provide a test environment
 
-Developers often ask us how long it takes for a plugin to be reviewed for publishing to the Grafana [plugin catalog](https://grafana.com/plugins). Although we [can't provide estimates](/publish-a-plugin/publish-a-plugin#how-long-does-it-take-to-review-a-submission), we are always looking for ways to reduce cycle times.
+:::note
+
+Provisioning is not required as part of the plugin submission process but will speed the review.
+
+:::
+
+Developers often ask us how long it takes for a plugin to be reviewed for publishing to the Grafana [plugin catalog](https://grafana.com/plugins). Although we [can't provide estimates](/publish-a-plugin/publish-a-plugin#how-long-does-it-take-to-review-a-submission), there's ways to reduce cycle times.
 
 By far the most time consuming aspect of a plugin's review is the creation of a suitable test environment so we can verify its behavior. This step often involves a number of back-and-forth conversations between the plugin developer and the review team.
 
-To drastically improve the review time, developers can provide this themselves by [_provisioning_](https://grafana.com/docs/grafana/latest/administration/provisioning/#provision-grafana) their plugin. Provisioning refers to the process of preparing and configuring a test environment within the plugin's [Docker development environment](/get-started/set-up-development-environment).
+To improve the review time, add [_provisioning_](https://grafana.com/docs/grafana/latest/administration/provisioning/#provision-grafana) to your plugin. Provisioning refers to the process of preparing and configuring a test environment within the plugin's [Docker development environment](/get-started/set-up-development-environment).
 
-## Why should plugin developers care about this?
+## Why provisioning test environments?
 
 There are several benefits to provisioning:
 
@@ -27,28 +33,25 @@ There are several benefits to provisioning:
 - **Easier set up for e2e tests.** By provisioning dashboards, e2e tests can run against specific scenarios across local development and in CI.
 - **Improved clarity.** We have found that provisioned plugins make it easier for tech-savvy users to understand how the plugin works.
 
-## Mechanism to provide a test environment
+## How to provide a test environment
 
-Grafana can be configured to have resources installed and enabled through a mechanism known as [provisioning](https://grafana.com/docs/grafana/latest/administration/provisioning/#provision-grafana), where resources are configured in a YAML file under a `/provisioning` directory.
+You can configure Grafana to have resources installed and enabled through a mechanism known as [provisioning](https://grafana.com/docs/grafana/latest/administration/provisioning/#provision-grafana), where resources are configured in a YAML file under a `/provisioning` directory.
 
-Since create-plugin v2.8.0, we generate provisioning capabilities for all plugin types (apps, scenes-apps, datasources, panels), and to include a sample dashboard as part of create-plugin.
+Starting in v2.8.0, `create-plugin` generates provisioning capabilities for all plugin types (apps, scenes-apps, datasources, panels) and includes a sample dashboard.
 
-## What do plugin developers need to do?
+### What do you need to do?
 
-:::note
+To provision follow these steps:
 
-Provisioning is not required; it's an optional part of the plugin submission process that will speed the review.
+1. Run the `create-plugin` tool to generate the `provisioning` folder with additional files based on the plugin type selected.
+1. When you run the Docker development environment, these files are used to automatically install (and if applicable, _enable_) your plugin and a sample dashboard.
 
-:::
+Notes:
 
-1. When you run the create-plugin tool, it will generate a folder called `provisioning` with additional files based on the plugin type selected.
-1. When you run the Docker development environment, these files are used to automatically install (and if applicable, _enable_) your plugin and a sample dashboard.
-1. We recommended that you use and update the sample dashboard to continuously verify behavior as part of your development process. And, as appropriate, configure your plugin so that it can return data.
+- Use and update the sample dashboard to continuously verify behavior as part of your development process. If appropriate, configure your plugin so that it can return data.
+
+- If you scaffolded your plugin with a previous version of `create-plugin`, you can run a new command to add the missing provisioning files.
 
-:::note
 
-In the case where a plugin has been scaffolded with a previous version of create-plugin, a new command can be run to retrospectively add the provisioning files.
 
-:::
 
----

docusaurus/docs/publish-a-plugin/publish-or-update-a-plugin.md

@@ -14,9 +14,9 @@ keywords:
 
 # Publish or update a plugin
 
-You've just built your plugin; now you want to share it with the world. Publishing your plugin to the [Grafana plugin catalog](https://grafana.com/plugins) makes it easily discoverable by millions of Grafana users.
+You've just built your plugin and now you want to share it with the world! 
 
-In this guide you learn how to manage the lifecycle of a plugin in the catalog, from publishing and updating to potentially deprecating.
+Publishing your plugin to the [Grafana plugin catalog](https://grafana.com/plugins) makes it easily discoverable by millions of Grafana users. Read on to learn how to manage the lifecycle of a plugin in the catalog, from publishing and updating to potentially deprecating.
 
 ## Before you begin