Docs: Update contribution guides (#534)

CONTRIBUTING.md

@@ -65,7 +65,7 @@ Once it's filed:
 
 - The project team will label the issue.
 - The project team will evaluate the feature request, possibly asking you more questions to understand its purpose and any relevant requirements. If the issue is closed, the team will convey their reasoning and suggest an alternative path forward.
-- If the feature request is accepted, it will be marked for implementation with `feature-accepted`, which can then be done by either a core team member or by anyone in the community who wants to [contribute code](#contribute-code).
+- If the feature request is accepted it can then be worked on by either a core team member or by anyone in the community who wants to [contribute code](#contribute-code).
 
 Note: The team is unlikely to be able to accept every single feature request that is filed. Please understand if they need to say no.
 
@@ -78,14 +78,13 @@ If this seems like a lot or you aren't able to do all this setup, you might also
 If you want to go the usual route and run the project locally, though:
 
 - [Install Node.js](https://nodejs.org/en/download/)
-- [Install yarn](https://classic.yarnpkg.com/lang/en/docs/install)
 - [Fork the project](https://guides.github.com/activities/forking/#fork)
 
 Then in your terminal:
 
 - `cd path/to/your/clone`
-- `yarn install`
-- `yarn test && yarn build`
+- `npm install`
+- `npm run test && npm run build`
 
 And you should be ready to go!
 
@@ -111,18 +110,20 @@ Documentation contributions of any size are welcome! Feel free to file a PR even
 To contribute documentation:
 
 - [Set up the project](#project-setup).
-- Edit or add any relevant documentation.
+- Run `npm run docs` to start a development server for the [documentation website](./docusaurus/website/).
+- Edit or add any relevant [documentation](./docusaurus/docs/).
 - Make sure your changes are formatted correctly and consistently with the rest of the documentation.
 - Re-read what you wrote, and run a spellchecker on it to make sure you didn't miss anything.
 - Go to https://github.com/grafana/plugin-tools/pulls and open a new pull request with your changes.
 - Please make use of the Pull Request Template. If your PR is connected to an open issue, add a line in your PR's description that says `Fixes: #123`, where `#123` is the number of the issue you're fixing.
+- If you are a maintainer add the `type/docs` and `no-changelog` labels to the PR.
 
 Once you've filed the PR:
 
 - One or more maintainers will use GitHub's review feature to review your PR.
 - If the maintainer asks for any changes, edit your changes, push, and ask for another review.
 - If the maintainer decides to pass on your PR, they will thank you for the contribution and explain why they won't be accepting the changes. That's ok! We still really appreciate you taking the time to do it, and we don't take that lightly. 💚
-- If your PR gets accepted, it will be marked as such, and merged into the `latest` branch soon after. Your contribution will be distributed to the masses next time the maintainers [create a release](#create-a-release)
+- If your PR gets accepted, it will be marked as such, and merged into the `latest` branch soon after. Your contribution will be distributed to the masses once the PR is merged.
 
 ## Contribute Code
 
@@ -135,6 +136,7 @@ The main difference between code contributions and documentation contributions i
 To contribute code:
 
 - [Set up the project](#project-setup).
+- Review the CONTRIBUTING.md file for the package/s you are working on.
 - Make any necessary changes to the source code.
 - Include any [additional documentation](#contribute-documentation) the changes might need.
 - Write tests that verify that your contribution works as expected.

README.md

@@ -9,16 +9,18 @@
   <p>Create and Sign Grafana plugins with ease.</p>
 </div>
 <div align="center">
-  <a href="https://github.com/grafana/plugin-tools/actions/workflows/ci.yml"
-    ><img
-      src="https://github.com/grafana/plugin-tools/actions/workflows/ci.yml/badge.svg"
-      alt="Node CI" /></a
-  >&nbsp;
-  <a href="https://github.com/intuit/auto"
-    ><img
-      src="https://img.shields.io/badge/release-auto.svg?colorA=888888&amp;colorB=9B065A&amp;label=auto"
-      alt="Auto Release"
-  /></a>
+  <a href="https://github.com/grafana/plugin-tools/actions/workflows/ci.yml">
+    <img src="https://github.com/grafana/plugin-tools/actions/workflows/ci.yml/badge.svg" alt="Node CI" />
+  </a>&nbsp;
+  <a href="https://nodejs.org">
+    <img src="https://img.shields.io/badge/NPM-%23CB3837.svg?style=for-the-badge&amp;logo=npm&amp;logoColor=white" alt="NPM" />
+  </a>&nbsp;
+  <a href="https://nx.dev/">
+    <img src="https://img.shields.io/badge/nx-143055?style=for-the-badge&amp;logo=nx&amp;logoColor=white" alt="Nx" />
+  </a>&nbsp;
+  <a href="https://github.com/intuit/auto">
+    <img src="https://img.shields.io/badge/release-auto.svg?colorA=888888&amp;colorB=9B065A&amp;label=auto" alt="Auto Release" />
+  </a>
   <br />
   <br />
 </div>
@@ -30,12 +32,16 @@ This is a mono-repo of NPM packages to help plugin developers extend Grafana in
 | Create Plugin | Scaffold a Grafana Plugin | [Link](./packages/create-plugin/README.md) | [![npm](https://img.shields.io/npm/v/@grafana/create-plugin)](https://www.npmjs.com/package/@grafana/create-plugin) | [![npm](https://img.shields.io/npm/dw/@grafana/create-plugin)](https://npmcharts.com/compare/@grafana/create-plugin?interval=7) |
 | Sign Plugin   | Sign a Grafana Plugin     | [Link](./packages/sign-plugin/README.md)   | [![npm](https://img.shields.io/npm/v/@grafana/sign-plugin)](https://www.npmjs.com/package/@grafana/sign-plugin)     | [![npm](https://img.shields.io/npm/dw/@grafana/sign-plugin)](https://npmcharts.com/compare/@grafana/sign-plugin?interval=7)     |
 
+### Overview
+
+This Mono-repo uses [NPM](https://nodejs.org) for package management, [NX](https://nx.dev/) to efficiently orchestrate tasks across the codebase, and [Auto](https://intuit.github.io/auto/) for streamlined and automated package publishing. We've carefully chosen and integrated these technologies to enhance development workflows. Before diving into the codebase, make sure to consult the [contributing guide](./CONTRIBUTING.md) for a smooth collaboration experience.
+
 ### Additional resources
 
-📖 Learn from tutorials and documenation in the [Grafana developer portal](https://grafana.com/developers).  
-✨ Gain inspiration from our [plugin examples](https://github.com/grafana/grafana-plugin-examples/) to get started quickly and implement new features in your plugin.  
-🛠️ Use the [Grafana plugin SDK for Go](https://github.com/grafana/grafana-plugin-sdk-go) to simplify the development of backend components.  
-✅ Ensure your plugin is ready for publishing to the [Grafana plugin catalog](https://grafana.com/grafana/plugins/) with our [validator](https://github.com/grafana/plugin-validator/) tool.  
+📖 Learn from tutorials and documentation in the [Grafana developer portal](https://grafana.com/developers).
+✨ Gain inspiration from our [plugin examples](https://github.com/grafana/grafana-plugin-examples/) to get started quickly and implement new features in your plugin.
+🛠️ Use the [Grafana plugin SDK for Go](https://github.com/grafana/grafana-plugin-sdk-go) to simplify the development of backend components.
+✅ Ensure your plugin is ready for publishing to the [Grafana plugin catalog](https://grafana.com/grafana/plugins/) with our [validator](https://github.com/grafana/plugin-validator/) tool.
 
 ## Contributors ✨
 

docusaurus/website/CONTRIBUTING.md

@@ -0,0 +1,81 @@
+# Contributing to Grafana / Plugin Tools / Website
+
+We are always grateful to receive contribution!<br />
+The following guidelines help you on how to start with the codebase and how to submit your work.
+
+## Installation
+
+### Prerequisites
+
+You need to have `npm` installed.
+
+### Installing
+
+```bash
+git clone git@github.com:grafana/plugin-tools.git
+cd plugin-tools
+npm install
+```
+
+## Overview
+
+### Technologies
+
+- [**`Docusaurus`**](https://docusaurus.io/) - the documentation website is built with docusaurus
+
+### Folder structure
+
+`/docusaurus` consists of the following folder structure:
+
+```js
+docusaurus/
+├── docs/ // the website documentation files
+│   ├── get-started/
+│   │   ├── _category_.json // category item metadata
+│   │   ├── folder-structure.md // documentation file
+│   │   └── get-started.mdx // documentation file using react components
+│   ├── shared/ // special directory for sharing text
+│   └── snippets/ // special directory for command snippets
+└── website/ // website source code
+    ├── plugins/ // location of docusaurus custom plugins
+    ├── src/ // react / js source code for website
+    │   ├── components
+    │   ├── css
+    │   ├── pages
+    │   └── theme
+    ├── static/ // folder for static assets
+    │   ├── font
+    │   └── img
+    ├── docusaurus.config.js
+    └── package.json
+```
+
+For futher information on working with docusaurus please consult the [official docs](https://docusaurus.io/docs/category/guides).
+
+## Development
+
+There are a collection of [commands](#commmands) to assist with developing the website. Please read the main [contributing guide](../../CONTRIBUTING.md) before contributing any code or documentation changes to the project.
+
+### Commmands
+
+Below are the main commands used for developing the website. They can be run by either `npx nx run website:<name_of_command>`, `npm run <name_of_command> -w website` or navigating to `docusaurus/website` and running the command directly as detailed below.
+
+```shell
+npm run start # starts a local development server to preview changes as files are edited.
+```
+
+```shell
+npm run build # creates a production build of the website.
+```
+
+```shell
+npm run serve # use this command to run the production build locally (requires the build command to be run first).
+```
+
+```shell
+npm run clear # clears the docusaurus cache
+```
+
+### Conventions
+
+Please refer to the [Grafana Writers' Toolkit](https://grafana.com/docs/writers-toolkit/).

packages/create-plugin/CONTRIBUTING.md

@@ -48,7 +48,7 @@ There are a collection of [commands](#commmands) to assist with developing `crea
 
 ### Commmands
 
-Below are the main commands used for developing `create-plugin`. They can be run by either `yarn workspace @grafana/create-plugin run <name_of_command>` or navigating to `packages/create-plugin` and running the command directly as detailed below.
+Below are the main commands used for developing `create-plugin`. They can be run by either `npx nx run @grafana/create-plugin:<name_of_command>`, `npm run <name_of_command> -w @grafana/create-plugin` or navigating to `packages/create-plugin` and running the command directly as detailed below.
 
 ```shell
 npm run build # used to build @grafana/create-plugin
@@ -77,3 +77,5 @@ _Work in progress._
 ### Developing the templates
 
 The templates are used by Plop to scaffold Grafana plugins. Whilst they appear to be the intended filetype they are infact treated as markdown by Plop when it runs. As such we need to be mindful of syntax and to [escape particular characters](https://handlebarsjs.com/guide/expressions.html#whitespace-control) where necessary. The [github/ci.yml](./templates/github/ci/.github/workflows/ci.yml) file is a good example of this.
+
+Note that certain files are intentionally named differently (e.g. npmrc, package.json). This is done due to other tooling preventing the files from being packaged for NPM or breaking other tools during local development.

packages/sign-plugin/CONTRIBUTING.md

@@ -33,7 +33,7 @@ There are a collection of [commands](#commmands) to assist with developing `sign
 
 ### Commmands
 
-Below are the main commands used for developing `sign-plugin`. They can be run by either `yarn workspace @grafana/sign-plugin run <name_of_command>` or navigating to `packages/sign-plugin` and running the command directly as detailed below.
+Below are the main commands used for developing `sign-plugin`. Below are the main commands used for developing `sign-plugin`. They can be run by either `npx nx run @grafana/sign-plugin:<name_of_command>`, `npm run <name_of_command> -w @grafana/sign-plugin` or navigating to `packages/sign-plugin` and running the command directly as detailed below.
 
 ```shell
 npm build # used to build @grafana/sign-plugin
@@ -46,11 +46,3 @@ npm dev # watches for changes to files and rebuilds @grafana/sign-plugin automat
 ### Conventions
 
 _Work in progress._
-
-### Developing the templates
-
-_Work in progress._
-
-### Submitting a Pull Request
-
-_Work in progress._