Add a contributing and releasing guide

CONTRIBUTING.md

@@ -0,0 +1,72 @@
+# Contributing Guidelines
+
+This document is a guide to help you through the process of contributing to the `grafana-vs-code-extension`.
+
+## Developing the extension
+
+### Create a fork
+
+[Fork][fork], then clone the repository:
+
+```shell
+git clone [email protected]:{your_github_username}/grafana-vs-code-extension.git
+cd grafana-vs-code-extension
+git remote add upstream https://github.com/grafana/grafana-vs-code-extension.git
+git fetch upstream
+```
+
+### Install `devbox`
+
+This repository relies on [devbox](https://www.jetify.com/devbox/docs/) to manage all
+the tools and dependencies needed for its development.
+
+A shell including all the required tools is accessible via:
+
+```shell
+devbox shell
+```
+
+This shell can be exited like any other shell, with `exit` or `CTRL+D`.
+
+One-off commands can be executed within the devbox shell as well:
+
+```shell
+devbox run node --version
+```
+
+### Install dependencies
+
+```shell
+devbox run yarn install
+```
+
+### Run the extension
+
+Compile the extension, and keep watching for changes:
+
+```shell
+devbox run yarn watch
+```
+
+Open this repository in VS Code, then press `F5` to start the extension locally.
+
+### Make changes
+
+To make changes to this codebase, follow the instructions on running the extension. Then, in your original VS Code window, make changes to the code base.
+
+Restart the extension with either <kbd>CTRL</kbd> + <kbd>SHIFT</kbd> + <kbd>F5</kbd> (<kbd>CMD</kbd> + <kbd>SHIFT</kbd> + <kbd>F5</kbd> on a Mac) or by clicking the green restart circle.
+
+Debug logs and dev tools can be accessed with <kbd>CTRL</kbd> + <kbd>SHIFT</kbd> + <kbd>I</kbd> on the VS Code development host.
+
+## Releasing the extension
+
+Releasing is a two step process:
+
+1. Prepare the release by updating the version number in `package.json` and describing what changed in the `CHANGELOG.md` file. See the [release preparation commit for `v0.0.19`](https://github.com/grafana/grafana-vs-code-extension/commit/71299f05d96391ce10b40bfe4de812955ace56dd). Open a pull request for this commit, get it reviewed and merged.
+2. Trigger the release pipeline by creating and pushing a tag: `git tag {version} && git push origin {version}`
+
+> [!NOTE]
+> The release pipeline creates and publishes a `.vsix` artifact to Open VSX, the Visual Studio Marketplace, as well as a GitHub release.
+
+
+[fork]: https://github.com/grafana/grafana-vs-code-extension/fork

README.md

@@ -10,16 +10,6 @@ However, some wish to use software development tools (e.g. git) to manage their
 
 Managing dashboards as code moves the single source of truth from Grafana itself to your version control system, which allows for dashboards to participate in gitops style workflows that are commonly used for much of the rest of software development.
 
-> **This library is experimental**
->
-> The code in this repository should be considered experimental. Documentation is only
-> available alongside the code. It comes without support, but we are keen to receive
-> feedback on the product and suggestions on how to improve it, though we cannot commit to
-> resolution of any particular issue. No SLAs are available. It is not meant to be used in
-> production environments, and the risks are unknown/high.
->
-> Additional information can be found in [Release life cycle for Grafana Labs](https://grafana.com/docs/release-life-cycle/).
-
 ## Why Work With Dashboards as Code?
 
 - JSON dashboards can be stored in your version control system. This provides a simple solution for rollback, history, auditing, and even change control.
@@ -49,30 +39,35 @@ Managing dashboards as code moves the single source of truth from Grafana itself
 3. Open the Settings tab inside the extension (CTRL+, (comma) or `cmd` + `,` on Mac) and search for `grafana`. Then select `Extensions`.
 
 ### Configure the Extension
+
 1. Provide the default URL for your Grafana instance in the `URL` field. If you are using a local Grafana instance, the default value is `http://localhost:3000`.
 2. Create a [Service account in Grafana](https://grafana.com/docs/grafana/latest/administration/service-accounts/#create-a-service-account-in-grafana) and add a token to it.
 3. In the VS Code settings, click `Set your token, securely` then paste your token into the popup. Press ENTER.
 
 ### Using the Extension
+
 1. Open a folder on your computer that has some dashboard JSON (if you don't have any of your own, navigate to the `dashboards` folder of [this repo](https://github.com/grafana/grafana-vs-code-extension/tree/main/dashboards)).
 2. Right-click on a dashboard JSON file in the file explorer and select `Edit in Grafana`.
 3. Have fun!
 4. Note, clicking `save` on your dashboard will update the JSON file in your local folder.
 
-### Run from Repository
-1. If using local Grafana, start Grafana locally or via Docker.
-2. Run `yarn install` in this repo.
-3. Open this repo VS Code, then press `F5` to start the extension locally.
-4. Continue from step 4 above.
-
-### Develop
-To make changes to this codebase, follow the instructions about how to run from this repository. Then, in your original VS Code window, make changes to the extension. Then, restart the extension with either CTRL+SHIFT+F5 (CMD+SHIFT+F5 on a Mac) or by clicking the green restart circle.
-
-To view debug logs, use CTRL+SHIFT+P (CMD+SHIFT+P on Mac) then select "Developer: Open Webview Developer Tools".
-
 ## Extension Settings
+
 - `grafana-vscode.URL`: Set the URL of the Grafana instance you want to open the dashboard in. Defaults to 'http://localhost:3000'.
 - `grafana-vscode.service-account-token`: A Service Account token. This is stored in the operating system secret store. Defaults to an empty string.
 
 ## Extension communication with Grafana
 Details of how this extension communicates with Grafana is available [here](https://github.com/grafana/grafana-vs-code-extension/blob/main/how-it-works.md).
+
+## Contributing
+
+See our [contributing guide](CONTRIBUTING.md).
+
+## Maturity
+
+The code in this repository should be considered as "**public preview**" and is actively developed and maintained by Engineering teams at Grafana.
+
+While this extension is stable enough to be used in production environments, occasional breaking changes or bugs can be expected.
+
+> [!NOTE]
+> Bugs and issues are handled solely by Engineering teams. On-call support or SLAs are not available.