1# Developer guide 2 3This guide helps you get started developing Grafana Plugin SDK for Go. 4 5## Tooling 6 7Make sure you have the following tools installed before setting up your developer environment: 8 9- [Git](https://git-scm.com/) 10- [Go](https://golang.org/dl/) (see [go.mod](../go.mod#L3) for minimum required version) 11- [Mage](https://magefile.org/) 12 13## Building 14 15We use [Mage](https://magefile.org/) as our primary tool for development related tasks like building and testing etc. It should be run from the root of this repository. 16 17List available Mage targets that are available: 18 19```bash 20mage -l 21``` 22 23You can use the `build` target to verify all code compiles. It doesn't output any binary though. 24 25```bash 26mage -v build 27``` 28 29The `-v` flag can be used to show verbose output when running Mage targets. 30 31### Testing 32 33```bash 34mage test 35``` 36 37### Linting 38 39```bash 40mage lint 41``` 42 43### Generate Go code for Protobuf definitions 44 45A prerequisite is to have [protoc](http://google.github.io/proto-lens/installing-protoc.html) installed and available in your path. 46 47Next, you need to have [protoc-gen-go](https://github.com/golang/protobuf/tree/v1.3.4#installation) installed and available in your path. It's very important that you match the version specified of `github.com/golang/protobuf` in [go.mod](go.mod) file, as of this writing it's v1.3.4. 48 49``` 50mage protobuf 51``` 52 53### Changing `generic_*.go` files in the `data` package 54 55Currently [genny](https://github.com/cheekybits/genny) is used for generating some go code. If you make changes to generic template files then `genny` needs to be installed, and then `mage dataGenerate`. Changed generated files should be committed with the change in the template files. 56 57### Dependency management 58 59We use Go modules for managing Go dependencies. After you've updated/modified modules dependencies, please run `go mod tidy` to cleanup dependencies. 60 61## Releasing 62 63If you want to create a new version of the SDK for release, follow these steps: 64 65- Checkout the commit you want to tag (`git checkout <COMMIT_SHA>`) 66- Run [`gorelease`](https://pkg.go.dev/golang.org/x/exp/cmd/gorelease) to compare with the previous release. For example, when preparing to release v0.123.0: 67 68``` 69gorelease -base v0.122.0 -version v0.123.0 70github.com/grafana/grafana-plugin-sdk-go/backend/gtime 71------------------------------------------------------ 72Compatible changes: 73- package added 74 75v0.123.0 is a valid semantic version for this release. 76``` 77- Run `git tag <VERSION>` (For example **v0.123.0**) 78 - NOTE: We're using Lightweight Tags, so no other options are required 79- Run `git push origin <VERSION>` 80- Verify that the tag was create successfully [here](https://github.com/grafana/grafana-plugin-sdk-go/tags) 81- Edit the tag on GitHub and create a release from it. 82 - Use the tag name as title. 83 - Click on the _Auto-generate release notes_ button. 84 - Add a compatibility section and add the output of the command above. 85 86**Release notes example:** 87 88- Title: v0.123.0 89- Content: 90 91````md 92<!-- Auto generated release notes --> 93 94## Compatibility 95``` 96gorelease -base v0.122.0 -version v0.123.0 97github.com/grafana/grafana-plugin-sdk-go/backend/gtime 98------------------------------------------------------ 99Compatible changes: 100- package added 101 102v0.123.0 is a valid semantic version for this release. 103``` 104 105```` 106