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