grafana / plugin-tools

Create Grafana plugins with ease.
https://grafana.com/developers/plugin-tools/
Apache License 2.0
55 stars 27 forks source link

Improve docs for optional elements and reduce number of prompts #771

Open sympatheticmoose opened 4 months ago

sympatheticmoose commented 4 months ago

Extracted from https://github.com/grafana/plugin-tools/issues/750 : "I would like to know what's required at minimum for a plugin to build and execute. This would hopefully allow me to shorten the duration of an npm install and reduce the overall file size during development."

Create plugin is an opinionated tool for scaffolding plugins. We aim to provide developers with everything they need to develop a plugin which follows our best practices. However, this does include a number of optional elements, not strictly required, and there can be valid reasons why they may wish to omit or remove certain libraries or generated files. Some optional elements we expose to developers as prompts in the tool - for example the levitate compatibility check, whilst flexibility can be useful - it also complicates matters and slows down the getting started workflow.

We have recently introduced the ability to pass flags to create-plugin to allow it to be run without using the interactive prompts.

After generating a (frontend only) plugin we provide the following success message:

## What's next?

Run the following commands to get started:

    * cd ./org-name-app
    * npm install to install frontend dependencies.
    * npm run dev to build (and watch) the plugin frontend code.
    * docker-compose up to start a grafana development server. Restart this command after each time you run mage to run your new backend code.
    * Open http://localhost:3000 in your browser to create a dashboard to begin developing your plugin.

Note: We strongly recommend creating a new Git repository by running git init in ./org-name-app before continuing.

    * Learn more about Grafana Plugin Development at https://grafana.com/developers/plugin-tools

We also provide this documentation on folder structure in the get started guide: https://grafana.com/developers/plugin-tools/#step-2-open-the-generated-folder-structure and more details in: https://grafana.com/developers/plugin-tools/get-started/folder-structure

Note: we are still gathering feedback on improving our documentation structure, any references or recommended placement is subject to change from that exercise.

### Tasks
- [ ] Document the flags in https://grafana.com/developers/plugin-tools/get-started/prompt-cli-reference
- [ ] Improve folder structure documentation to better explain optional elements which could be removed (and why they are there in the first place - i.e. why we recommend them)
- [ ] Remove prompts for the GitHub actions to reduce the number of questions a developer has to answer.
GrafanaWriter commented 3 months ago

@josmperez - Should you own this issue, or wil @sympatheticmoose ? Either way, can we please triage so it isn't in our project as "Needs Triage"?

josmperez commented 3 months ago

I've added myself and @sympatheticmoose as owners and updated the status to Backlog (Docs Team).