@grafana/create-plugin 0.6.3 → 0.7.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+# v0.7.0 (Tue Nov 29 2022)
+
+#### 🚀 Enhancement
+
+- Create plugin: Introduce sign-plugin [#160](https://github.com/grafana/plugin-tools/pull/160) ([@jackw](https://github.com/jackw))
+
+#### Authors: 1
+
+- Jack Westbrook ([@jackw](https://github.com/jackw))
+
+---
+
 # v0.6.3 (Mon Nov 28 2022)
 
 #### 🐛 Bug Fix

package/dist/commands/generate.plopfile.js

@@ -31,6 +31,7 @@ var constants_1 = require("../constants");
 function default_1(plop) {
     plop.setHelper('if_eq', utils_handlebars_1.ifEq);
     plop.setHelper('normalize_id', utils_handlebars_1.normalizeId);
+    plop.setActionType('printSuccessMessage', printSuccessMessage);
     plop.setGenerator('create-plugin', {
         description: 'used to scaffold a grafana plugin',
         prompts: [
@@ -120,7 +121,11 @@ function default_1(plop) {
                 ? getActionsForTemplateFolder({ folderPath: constants_1.TEMPLATE_PATHS.isCompatibleWorkflow, exportPath: exportPath })
                 : [];
             var readmeActions = getActionsForReadme({ exportPath: exportPath });
-            return __spreadArray(__spreadArray(__spreadArray(__spreadArray([], pluginActions, true), ciWorkflowActions, true), readmeActions, true), isCompatibleWorkflowActions, true);
+            return __spreadArray(__spreadArray(__spreadArray(__spreadArray(__spreadArray([], pluginActions, true), ciWorkflowActions, true), readmeActions, true), isCompatibleWorkflowActions, true), [
+                {
+                    type: 'printSuccessMessage'
+                },
+            ], false);
         }
     });
 }
@@ -130,6 +135,7 @@ function getActionsForReadme(_a) {
     return [
         replacePatternWithTemplateInReadme('-- INSERT FRONTEND GETTING STARTED --', 'frontend-getting-started.md', exportPath),
         replacePatternWithTemplateInReadme('-- INSERT BACKEND GETTING STARTED --', 'backend-getting-started.md', exportPath),
+        replacePatternWithTemplateInReadme('-- INSERT DISTRIBUTING YOUR PLUGIN --', 'distributing-your-plugin.md', exportPath),
     ];
 }
 function replacePatternWithTemplateInReadme(pattern, partialsFile, exportPath) {
@@ -179,3 +185,14 @@ function getExportPath(pluginName, orgName, pluginType) {
         return path_1["default"].join(process.cwd(), (0, utils_handlebars_1.normalizeId)(pluginName, orgName, pluginType));
     }
 }
+function printSuccessMessage(answers) {
+    var directory = (0, utils_handlebars_1.normalizeId)(answers.pluginName, answers.orgName, answers.pluginType);
+    var commands = __spreadArray(__spreadArray([
+        '  * `yarn install` to install frontend dependencies.',
+        '  * `docker-compose up` to start a grafana development server.',
+        '  * `yarn dev` to build (and watch) the plugin frontend code.'
+    ], (answers.hasBackend ? ['  * `mage -v build:linux` to build the plugin backend code.'] : []), true), [
+        '  * Open http://localhost:3000 in your browser to create a dashboard to begin developing your plugin.',
+    ], false);
+    return "\n  Congratulations on scaffolding a Grafana ".concat(answers.pluginName, " plugin! \uD83D\uDE80\n\n  ## What's next?\n  Navigate into ./").concat(directory, " and run the following commands to get started:\n").concat(commands.map(function (command) { return command; }).join('\n'), "\n\n  View the README.md for futher information.\n  Learn more about Grafana Plugins at https://grafana.com/docs/grafana/latest/plugins/developing/development/\n\n");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grafana/create-plugin",
-  "version": "0.6.3",
+  "version": "0.7.0",
   "main": "index.js",
   "repository": {
     "directory": "packages/create-plugin",
@@ -60,5 +60,5 @@
   "engines": {
     "node": ">=16"
   },
-  "gitHead": "f1dc565ab40f62006c023bc3eda23e8ebeed6ae7"
+  "gitHead": "a9672bf8dfb3c26bcda4b2eb82ab57d4f1f0601d"
 }

package/src/commands/generate.plopfile.ts

@@ -27,6 +27,8 @@ export default function (plop: NodePlopAPI) {
   plop.setHelper('if_eq', ifEq);
   plop.setHelper('normalize_id', normalizeId);
 
+  plop.setActionType('printSuccessMessage', printSuccessMessage);
+
   plop.setGenerator('create-plugin', {
     description: 'used to scaffold a grafana plugin',
     prompts: [
@@ -139,7 +141,15 @@ export default function (plop: NodePlopAPI) {
       // Replace conditional bits in the Readme files
       const readmeActions = getActionsForReadme({ exportPath });
 
-      return [...pluginActions, ...ciWorkflowActions, ...readmeActions, ...isCompatibleWorkflowActions];
+      return [
+        ...pluginActions,
+        ...ciWorkflowActions,
+        ...readmeActions,
+        ...isCompatibleWorkflowActions,
+        {
+          type: 'printSuccessMessage',
+        },
+      ];
     },
   });
 }
@@ -156,6 +166,11 @@ function getActionsForReadme({ exportPath }: { exportPath: string }): ModifyActi
       'backend-getting-started.md',
       exportPath
     ),
+    replacePatternWithTemplateInReadme(
+      '-- INSERT DISTRIBUTING YOUR PLUGIN --',
+      'distributing-your-plugin.md',
+      exportPath
+    ),
   ];
 }
 
@@ -229,3 +244,27 @@ function getExportPath(pluginName: string, orgName: string, pluginType: PLUGIN_T
     return path.join(process.cwd(), normalizeId(pluginName, orgName, pluginType));
   }
 }
+
+function printSuccessMessage(answers: CliArgs) {
+  const directory = normalizeId(answers.pluginName, answers.orgName, answers.pluginType);
+
+  const commands = [
+    '  * `yarn install` to install frontend dependencies.',
+    '  * `docker-compose up` to start a grafana development server.',
+    '  * `yarn dev` to build (and watch) the plugin frontend code.',
+    ...(answers.hasBackend ? ['  * `mage -v build:linux` to build the plugin backend code.'] : []),
+    '  * Open http://localhost:3000 in your browser to create a dashboard to begin developing your plugin.',
+  ];
+
+  return `
+  Congratulations on scaffolding a Grafana ${answers.pluginName} plugin! 🚀
+
+  ## What's next?
+  Navigate into ./${directory} and run the following commands to get started:
+${commands.map((command) => command).join('\n')}
+
+  View the README.md for futher information.
+  Learn more about Grafana Plugins at https://grafana.com/docs/grafana/latest/plugins/developing/development/
+
+`;
+}

package/templates/_partials/distributing-your-plugin.md

@@ -0,0 +1,38 @@
+# Distributing your plugin
+
+When distributing a Grafana plugin either within the community or privately the plugin must be signed so the Grafana application can verify its authenticity. This can be done with the `@grafana/sign-plugin` package.
+
+_Note: It's not necessary to sign a plugin during development. The docker development environment that is scaffolded with `@grafana/create-plugin` caters for running the plugin without a signature._
+
+## Initial steps
+
+Before signing a plugin please read the Grafana [plugin publishing and signing criteria](https://grafana.com/docs/grafana/latest/developers/plugins/publishing-and-signing-criteria/) documentation carefully.
+
+`@grafana/create-plugin` has added the necessary commands and workflows to make signing and distributing a plugin via the grafana plugins catalog as straightforward as possible.
+
+Before signing a plugin for the first time please consult the Grafana [plugin signature levels](https://grafana.com/docs/grafana/latest/developers/plugins/sign-a-plugin/#plugin-signature-levels) documentation to understand the differences between the types of signature level.
+
+1. Create a [Grafana Cloud account](https://grafana.com/signup).
+2. Make sure that the first part of the plugin ID matches the slug of your Grafana Cloud account.
+   - _You can find the plugin ID in the plugin.json file inside your plugin directory. For example, if your account slug is `acmecorp`, you need to prefix the plugin ID with `acmecorp-`._
+3. Create a Grafana Cloud API key with the `PluginPublisher` role.
+4. Keep a record of this API key as it will be required for signing a plugin
+
+## Signing a plugin
+
+### Using Github actions release workflow
+
+If the plugin is using the github actions supplied with `@grafana/create-plugin` signing a plugin is included out of the box. The [release workflow](./.github/workflows/release.yml) can prepare everything to make submitting your plugin to Grafana as easy as possible. Before being able to sign the plugin however a secret needs adding to the Github repository.
+
+1. Please navigate to "settings > secrets > actions" within your repo to create secrets.
+2. Click "New repository secret"
+3. Name the secret "GRAFANA_API_KEY"
+4. Paste your Grafana Cloud API key in the Secret field
+5. Click "Add secret"
+
+#### Push a version tag
+
+To trigger the workflow we need to push a version tag to github. This can be achieved with the following steps:
+
+1. Run `npm version <major|minor|patch>`
+2. Run `git push origin main --follow-tags`

package/templates/app/README.md

@@ -11,6 +11,8 @@ App plugins can let you create a custom out-of-the-box monitoring experience by
 -- INSERT FRONTEND GETTING STARTED --
 {{#if hasBackend}}-- INSERT BACKEND GETTING STARTED --{{/if}}
 
+-- INSERT DISTRIBUTING YOUR PLUGIN --
+
 ## Learn more
 
 Below you can find source code for existing app plugins and other related documentation.

package/templates/common/package.json

@@ -12,7 +12,8 @@
     "lint:fix": "yarn lint --fix",
     "e2e": "yarn cypress install && yarn grafana-e2e run",
     "e2e:update": "yarn cypress install && yarn grafana-e2e run --update-screenshots",
-    "server": "docker-compose up --build"
+    "server": "docker-compose up --build",
+    "sign": "npx --yes @grafana/sign-plugin"
   },
   "author": "{{ sentenceCase orgName }}",
   "license": "Apache-2.0",

package/templates/datasource/README.md

@@ -11,6 +11,8 @@ Grafana supports a wide range of data sources, including Prometheus, MySQL, and
 -- INSERT FRONTEND GETTING STARTED --
 {{#if hasBackend}}-- INSERT BACKEND GETTING STARTED --{{/if}}
 
+-- INSERT DISTRIBUTING YOUR PLUGIN --
+
 ## Learn more
 
 Below you can find source code for existing app plugins and other related documentation.

package/templates/github/ci/.github/workflows/ci.yml

@@ -10,6 +10,7 @@ on:
     branches:
       - master
       - main
+
 jobs:
   build:
     runs-on: ubuntu-latest
@@ -19,34 +20,18 @@ jobs:
       - name: Setup Node.js environment
         uses: actions/setup-node@v3
         with:
-          node-version: '16.x'
-
-      - name: Get yarn cache directory path
-        id: yarn-cache-dir-path
-        run: echo "dir=$(yarn cache dir)" >> $GITHUB_OUTPUT
-
-      - name: Cache yarn cache
-        uses: actions/cache@v3
-        id: cache-yarn-cache
-        with:
-          path: $\{{ steps.yarn-cache-dir-path.outputs.dir }}
-          key: $\{{ runner.os }}-yarn-$\{{ hashFiles('**/yarn.lock') }}
-          restore-keys: |
-            $\{{ runner.os }}-yarn-
-
-      - name: Cache node_modules
-        id: cache-node-modules
-        uses: actions/cache@v3
-        with:
-          path: node_modules
-          key: $\{{ runner.os }}-$\{{ matrix.node-version }}-nodemodules-$\{{ hashFiles('**/yarn.lock') }}
-          restore-keys: |
-            $\{{ runner.os }}-$\{{ matrix.node-version }}-nodemodules-
-
+          node-version: '16'
+          cache: 'yarn'
       - name: Install dependencies
-        run: yarn install --frozen-lockfile
+        run: yarn install --immutable --prefer-offline
 
-      - name: Build and test frontend
+      - name: Check types
+        run: yarn typecheck
+      - name: Lint
+        run: yarn lint
+      - name: Unit tests
+        run: yarn test:ci
+      - name: Build frontend
         run: yarn build
 
       - name: Start grafana docker
@@ -55,7 +40,7 @@ jobs:
       - name: Run e2e tests
         run: yarn e2e
 
-      - name: stop grafana docker
+      - name: Stop grafana docker
         run: docker-compose down
 
       - name: Check for backend

package/templates/github/ci/.github/workflows/release.yml

@@ -4,52 +4,29 @@ name: Release
 on:
   push:
     tags:
-      - 'v*.*.*' # Run workflow on version tags, e.g. v1.0.0.
+      - 'v*' # Run workflow on version tags, e.g. v1.0.0.
 
 jobs:
   release:
     runs-on: ubuntu-latest
-
+    env:
+      GRAFANA_API_KEY: $\{{ secrets.GRAFANA_API_KEY }} # Requires a Grafana API key from Grafana.com.
     steps:
       - uses: actions/checkout@v3
 
       - name: Setup Node.js environment
         uses: actions/setup-node@v3
         with:
-          node-version: '16.x'
+          node-version: '16'
+          cache: 'yarn'
 
       - name: Setup Go environment
         uses: actions/setup-go@v3
         with:
           go-version: '1.19'
 
-      - name: Get yarn cache directory path
-        id: yarn-cache-dir-path
-        run: echo "dir=$(yarn cache dir)" >> $GITHUB_OUTPUT
-
-      - name: Cache yarn cache
-        uses: actions/cache@v3
-        id: cache-yarn-cache
-        with:
-          path: $\{{ steps.yarn-cache-dir-path.outputs.dir }}
-          key: $\{{ runner.os }}-yarn-$\{{ hashFiles('**/yarn.lock') }}
-          restore-keys: |
-            $\{{ runner.os }}-yarn-
-
-      - name: Cache node_modules
-        id: cache-node-modules
-        uses: actions/cache@v3
-        with:
-          path: node_modules
-          key: $\{{ runner.os }}-$\{{ matrix.node-version }}-nodemodules-$\{{ hashFiles('**/yarn.lock') }}
-          restore-keys: |
-            $\{{ runner.os }}-$\{{ matrix.node-version }}-nodemodules-
-
       - name: Install dependencies
-        run: yarn install --frozen-lockfile;
-        if: |
-          steps.cache-yarn-cache.outputs.cache-hit != 'true' ||
-          steps.cache-node-modules.outputs.cache-hit != 'true'
+        run: yarn install --immutable --prefer-offline
 
       - name: Build and test frontend
         run: yarn build
@@ -76,10 +53,15 @@ jobs:
           version: latest
           args: buildAll
 
+      - name: Warn missing Grafana API key
+        run: |
+          echo Please generate a Grafana API key: https://grafana.com/docs/grafana/latest/developers/plugins/sign-a-plugin/#generate-an-api-key
+          echo Once done please follow the instructions found here: https://github.com/$\{{github.repository}}/blob/main/README.md#using-github-actions-release-workflow
+        if: $\{{ env.GRAFANA_API_KEY == '' }}
+
       - name: Sign plugin
         run: yarn sign
-        env:
-          GRAFANA_API_KEY: $\{{ secrets.GRAFANA_API_KEY }} # Requires a Grafana API key from Grafana.com.
+        if: $\{{ env.GRAFANA_API_KEY != '' }}
 
       - name: Get plugin metadata
         id: metadata
@@ -117,49 +99,35 @@ jobs:
           md5sum $\{{ steps.metadata.outputs.archive }} > $\{{ steps.metadata.outputs.archive-checksum }}
           echo "checksum=$(cat ./$\{{ steps.metadata.outputs.archive-checksum }} | cut -d' ' -f1)" >> $GITHUB_OUTPUT
 
-      - name: Lint plugin
+      - name: Validate plugin
         run: |
           git clone https://github.com/grafana/plugin-validator
           pushd ./plugin-validator/pkg/cmd/plugincheck2
           go install
           popd
-          plugincheck2 -config ./plugin-validator/config/publishing.yaml $\{{ steps.metadata.outputs.archive }}
+          plugincheck2 -config ./plugin-validator/config/default.yaml $\{{ steps.metadata.outputs.archive }}
 
-      - name: Create release
-        id: create_release
-        uses: actions/create-release@v1
-        env:
-          GITHUB_TOKEN: $\{{ secrets.GITHUB_TOKEN }}
+      - name: Create Github release
+        uses: softprops/action-gh-release@v1
         with:
-          tag_name: $\{{ github.ref }}
-          release_name: Release $\{{ github.ref }}
-          body_path: $\{{ steps.changelog.outputs.path }}
           draft: true
-
-      - name: Add plugin to release
-        id: upload-plugin-asset
-        uses: actions/upload-release-asset@v1
-        env:
-          GITHUB_TOKEN: $\{{ secrets.GITHUB_TOKEN }}
-        with:
-          upload_url: $\{{ steps.create_release.outputs.upload_url }}
-          asset_path: ./$\{{ steps.metadata.outputs.archive }}
-          asset_name: $\{{ steps.metadata.outputs.archive }}
-          asset_content_type: application/zip
-
-      - name: Add checksum to release
-        id: upload-checksum-asset
-        uses: actions/upload-release-asset@v1
-        env:
-          GITHUB_TOKEN: $\{{ secrets.GITHUB_TOKEN }}
-        with:
-          upload_url: $\{{ steps.create_release.outputs.upload_url }}
-          asset_path: ./$\{{ steps.metadata.outputs.archive-checksum }}
-          asset_name: $\{{ steps.metadata.outputs.archive-checksum }}
-          asset_content_type: text/plain
-
-      - name: Publish to Grafana.com
-        run: |
-          echo A draft release has been created for your plugin. Please review and publish it. Then submit your plugin to grafana.com/plugins by opening a PR to https://github.com/grafana/grafana-plugin-repository with the following entry:
-          echo
-          echo '{ "id": "$\{{ steps.metadata.outputs.plugin-id }}", "type": "$\{{ steps.metadata.outputs.plugin-type }}", "url": "https://github.com/$\{{ github.repository }}", "versions": [ { "version": "$\{{ steps.metadata.outputs.plugin-version }}", "commit": "$\{{ github.sha }}", "url": "https://github.com/$\{{ github.repository }}", "download": { "any": { "url": "https://github.com/$\{{ github.repository }}/releases/download/v$\{{ steps.metadata.outputs.plugin-version }}/$\{{ steps.metadata.outputs.archive }}", "md5": "$\{{ steps.package-plugin.outputs.checksum }}" } } } ] }' | jq .
+          generate_release_notes: true
+          files: |
+            ./$\{{ steps.metadata.outputs.archive }}
+            ./$\{{ steps.metadata.outputs.archive-checksum }}
+          body: |
+            **This Github draft release has been created for your plugin.**
+
+            _Note: if this is the first release for your plugin please consult the [distributing-your-plugin section](https://github.com/$\{{github.repository}}/blob/main/README.md#distributing-your-plugin) of the README_
+
+            If you would like to submit this release to Grafana please consider the following steps:
+
+            - Check the Validate plugin step in the [release workflow](https://github.com/$\{{github.repository}}/commit/$\{{github.sha}}/checks/$\{{github.run_id}}) for any warnings that need attention
+            - Navigate to https://grafana.com/auth/sign-in/ to sign into your account
+            - Once logged in click **My Plugins** in the admin navigation
+            - Click the **Submit Plugin** button
+            - Fill in the Plugin Submission form:
+              - Paste this [.zip asset link](https://github.com/$\{{ github.repository }}/releases/download/v$\{{ steps.metadata.outputs.plugin-version }}/$\{{ steps.metadata.outputs.archive }}) in the Plugin URL field
+              - Paste this [.zip.md5 link](https://github.com/$\{{ github.repository }}/releases/download/v$\{{ steps.metadata.outputs.plugin-version }}/$\{{ steps.metadata.outputs.archive-checksum }}) in the MD5 field
+
+            Once done please remove these instructions and publish this release.

package/templates/github/is-compatible/.github/workflows/is-compatible.yml

@@ -1,5 +1,5 @@
 name: Latest Grafana API compatibility check
-on: [push, pull_request]
+on: [pull_request]
 
 jobs:
   compatibilitycheck:
@@ -9,8 +9,9 @@ jobs:
       - uses: actions/setup-node@v3
         with:
           node-version: '16'
+          cache: 'yarn'
       - name: Install dependencies
-        run: yarn install
+        run: yarn install --immutable --prefer-offline
       - name: Build plugin
         run: yarn build
       - name: Compatibility check

package/templates/panel/README.md

@@ -13,6 +13,8 @@ Use panel plugins when you want to do things like visualize data returned by dat
 -- INSERT FRONTEND GETTING STARTED --
 {{#if hasBackend}}-- INSERT BACKEND GETTING STARTED --{{/if}}
 
+-- INSERT DISTRIBUTING YOUR PLUGIN --
+
 ## Learn more
 
 Below you can find source code for existing app plugins and other related documentation.