Skip to content

Commit 00e880a

Browse files
marefrbergquistaknuds1
authored
Docs: Basic repository documentation/guides, security policy and issue and PR templates (#164)
Cleanup readme for now by removing outdated example and linking to contribution and development guides plus adding some nice badges Adds issues and PR templates (copy from grafana repo with modifications) Adds security policy (copy from grafana repo) Adds contributing guideline (copy from grafana repo with modifications)- Adds development guideline Co-authored-by: Carl Bergquist <[email protected]> Co-authored-by: Arve Knudsen <[email protected]>
1 parent 3f66a49 commit 00e880a

9 files changed

+238
-45
lines changed

‎.github/ISSUE_TEMPLATE/1-bug_report.md

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
---
2+
name: Bug report
3+
about: Report a bug
4+
labels: 'bug'
5+
---
6+
7+
<!--
8+
Please use this template while reporting a bug and provide as much info as possible.
9+
Questions should be posted to https://community.grafana.com
10+
-->
11+
12+
**What happened**:
13+
14+
**What you expected to happen**:
15+
16+
**How to reproduce it (as minimally and precisely as possible)**:
17+
18+
**Anything else we need to know?**:
19+
20+
**Environment**:
21+
- SDK version:
22+
- Grafana version:
23+
- Go version:

‎.github/ISSUE_TEMPLATE/2-enhancement_request.md

+11
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
---
2+
name: Enhancement request
3+
about: Suggest an enhancement or new feature
4+
labels: 'enhancement'
5+
---
6+
7+
<!-- Please only use this template for submitting enhancement requests -->
8+
9+
**What would you like to be added**:
10+
11+
**Why is this needed**:

‎.github/ISSUE_TEMPLATE/config.yml

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
blank_issues_enabled: false
2+
contact_links:
3+
- name: Questions & Help
4+
url: https://community.grafana.com
5+
about: Please ask and answer questions here.

‎.github/PULL_REQUEST_TEMPLATE.md

+29
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
<!--
2+
3+
Thank you for sending a pull request! Here are some tips:
4+
5+
1. If this is your first time, please read our contribution guide at https://github.com/grafana/grafana-plugin-sdk-go/blob/master/CONTRIBUTING.md
6+
7+
2. Ensure you include and run the appropriate tests as part of your Pull Request.
8+
9+
3. If the Pull Request is a work in progress, make use of GitHub's "Draft PR" feature and mark it as such.
10+
11+
4. If you can not merge your Pull Request due to a merge conflict, Rebase it. This gets it in sync with the master branch.
12+
13+
-->
14+
15+
**What this PR does / why we need it**:
16+
17+
**Which issue(s) this PR fixes**:
18+
19+
<!--
20+
21+
* Automatically closes linked issue when the Pull Request is merged.
22+
23+
Usage: "Fixes #<issue number>", or "Fixes (paste link of issue)"
24+
25+
-->
26+
27+
Fixes #
28+
29+
**Special notes for your reviewer**:

‎CODE_OF_CONDUCT.md

+46
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# Contributor Covenant Code of Conduct
2+
3+
## Our Pledge
4+
5+
In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to make participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
6+
7+
## Our Standards
8+
9+
Examples of behavior that contributes to creating a positive environment include:
10+
11+
* Using welcoming and inclusive language
12+
* Being respectful of differing viewpoints and experiences
13+
* Gracefully accepting constructive criticism
14+
* Focusing on what is best for the community
15+
* Showing empathy towards other community members
16+
17+
Examples of unacceptable behavior by participants include:
18+
19+
* The use of sexualized language or imagery and unwelcome sexual attention or advances
20+
* Trolling, insulting/derogatory comments, and personal or political attacks
21+
* Public or private harassment
22+
* Publishing others' private information, such as a physical or electronic address, without explicit permission
23+
* Other conduct which could reasonably be considered inappropriate in a professional setting
24+
25+
## Our Responsibilities
26+
27+
Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
28+
29+
Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
30+
31+
## Scope
32+
33+
This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.
34+
35+
## Enforcement
36+
37+
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at [email protected]. The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
38+
39+
Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
40+
41+
## Attribution
42+
43+
This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at [http://contributor-covenant.org/version/1/4][version]
44+
45+
[homepage]: http://contributor-covenant.org
46+
[version]: http://contributor-covenant.org/version/1/4/

‎CONTRIBUTING.md

+32
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# Contributing
2+
3+
Thank you for your interest in contributing to Grafana Plugin SDK for Go! We welcome all people who want to contribute in a healthy and constructive manner within our community. To help us create a safe and positive community experience for all, we require all participants to adhere to the [Code of Conduct](CODE_OF_CONDUCT.md).
4+
5+
This document is a guide to help you through the process of contributing to Grafana Plugin SDK for Go.
6+
7+
## Become a contributor
8+
9+
You can contribute to Grafana Plugin SDK for Go in several ways. Here are some examples:
10+
11+
- Contribute to the Grafana SDK for Go codebase.
12+
- Report bugs and enhancements.
13+
14+
For more ways to contribute, check out the [Open Source Guides](https://opensource.guide/how-to-contribute/).
15+
16+
### Report bugs
17+
18+
Report a bug by submitting a [bug report](https://github.com/grafana/grafana-plugin-sdk-go/issues/new?labels=bug&template=1-bug_report.md). Make sure that you provide as much information as possible on how to reproduce the bug.
19+
20+
Before submitting a new issue, try to make sure someone hasn't already reported the problem. Look through the [existing issues](https://github.com/grafana/grafana-plugin-sdk-go/issues) for similar issues.
21+
22+
#### Security issues
23+
24+
If you believe you've found a security vulnerability, please read our [security policy](https://github.com/grafana/grafana-plugin-sdk-go/security/policy) for more details.
25+
26+
### Suggest enhancements
27+
28+
If you have an idea of how to improve Grafana Plugin SDK for Go, submit an [enhancement request](https://github.com/grafana/grafana-plugin-sdk-go/issues/new?labels=enhancement&template=2-enhancement_request.md).
29+
30+
## Where do I go from here?
31+
32+
- Set up your [development environment](contribute/developer-guide.md).

‎README.md

+13-45
Original file line numberDiff line numberDiff line change
@@ -1,55 +1,23 @@
11
# Grafana Plugin SDK for Go
22

3-
Develop Grafana backend plugins with this Go SDK.
3+
This SDK enables building [Grafana](https://github.com/grafana/grafana) backend plugins using Go.
44

5-
**Warning**: This SDK is currently in alpha and will likely have major breaking changes during early development. Please do not consider this SDK published until this warning has been removed.
5+
[![License](https://img.shields.io/github/license/grafana/grafana-plugin-sdk-go)](LICENSE)
6+
[![GoDoc](https://godoc.org/github.com/grafana/grafana-plugin-sdk-go?status.svg)](https://godoc.org/github.com/grafana/grafana-plugin-sdk-go)
7+
[![Go Report Card](https://goreportcard.com/badge/github.com/grafana/grafana-plugin-sdk-go)](https://goreportcard.com/report/github.com/grafana/grafana-plugin-sdk-go)
8+
[![Circle CI](https://img.shields.io/circleci/build/gh/grafana/grafana-plugin-sdk-go/master)](https://circleci.com/gh/grafana/grafana-plugin-sdk-go?branch=master)
69

7-
## Usage
10+
## Current state
811

9-
```go
10-
package main
12+
This SDK is still in development. The protocol between the Grafana server and the plugin SDK is considered stable, but we might introduce breaking changes in the SDK. This means that plugins using the older SDK should work with Grafana, but might lose out on new features and capabilities that we introduce in the SDK.
1113

12-
import (
13-
"context"
14-
"log"
15-
"os"
14+
## Contributing
1615

17-
gf "github.com/grafana/grafana-plugin-sdk-go"
18-
)
16+
If you're interested in contributing to this project:
1917

20-
const pluginID = "myorg-custom-datasource"
18+
- Start by reading the [Contributing guide](/CONTRIBUTING.md).
19+
- Learn how to set up your local environment, in our [Developer guide](/contribute/developer-guide.md).
2120

22-
type MyDataSource struct {
23-
logger *log.Logger
24-
}
21+
## License
2522

26-
func (d *MyDataSource) Query(ctx context.Context, tr gf.TimeRange, ds gf.DataSourceInfo, queries []gf.Query) ([]gf.QueryResult, error) {
27-
return []gf.QueryResult{}, nil
28-
}
29-
30-
func main() {
31-
logger := log.New(os.Stderr, "", 0)
32-
33-
srv := gf.NewServer()
34-
35-
srv.HandleDataSource(pluginID, &MyDataSource{
36-
logger: logger,
37-
})
38-
39-
if err := srv.Serve(); err != nil {
40-
logger.Fatal(err)
41-
}
42-
}
43-
```
44-
45-
## Developing
46-
47-
### Generate Go code for Protobuf definitions
48-
49-
```
50-
make protobuf
51-
```
52-
53-
### Changing `generic_*.go` files in the `data` package
54-
55-
Currently [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.
23+
[Apache 2.0 License](https://github.com/grafana/grafana-plugin-sdk-go/blob/master/LICENSE)

‎SECURITY.md

+20
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Reporting security issues
2+
3+
If you think you have found a security vulnerability, please send a report to [[email protected]](mailto:[email protected]). This address can be used for all of Grafana Labs's open source and commercial products (including but not limited to Grafana, Grafana Cloud, Grafana Enterprise, and grafana.com). We can accept only vulnerability reports at this address.
4+
5+
Please encrypt your message to us; please use our PGP key. The key fingerprint is:
6+
7+
F988 7BEA 027A 049F AE8E 5CAA D125 8932 BE24 C5CA
8+
9+
The key is available from [pgp.mit.edu](https://pgp.mit.edu/pks/lookup?op=get&search=0xF9887BEA027A049FAE8E5CAAD1258932BE24C5CA) by searching for [grafana](https://pgp.mit.edu/pks/lookup?search=grafana&op=index).
10+
11+
Grafana Labs will send you a response indicating the next steps in handling your report. After the initial reply to your report, the security team will keep you informed of the progress towards a fix and full announcement, and may ask for additional information or guidance.
12+
13+
**Important:** We ask you to not disclose the vulnerability before it have been fixed and announced, unless you received a response from the Grafana Labs security team that you can do so.
14+
15+
## Security announcements
16+
17+
We maintain a category on the community site called [Security Announcements](https://community.grafana.com/c/security-announcements),
18+
where we will post a summary, remediation, and mitigation details for any patch containing security fixes.
19+
20+
You can also subscribe to email updates to this category if you have a grafana.com account and sign on to the community site or track updates via an [RSS feed](https://community.grafana.com/c/security-announcements.rss).

‎contribute/developer-guide.md

+59
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# Developer guide
2+
3+
This guide helps you get started developing Grafana Plugin SDK for Go.
4+
5+
## Tooling
6+
7+
Make 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+
15+
We 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+
17+
List available Mage targets that are available:
18+
19+
```bash
20+
mage -l
21+
```
22+
23+
You can use the `build` target to verify all code compiles. It doesn't output any binary though.
24+
25+
```bash
26+
mage -v build
27+
```
28+
29+
The `-v` flag can be used to show verbose output when running Mage targets.
30+
31+
### Testing
32+
33+
```bash
34+
mage test
35+
```
36+
37+
### Linting
38+
39+
```bash
40+
mage lint
41+
```
42+
43+
### Generate Go code for Protobuf definitions
44+
45+
A prerequisite is to have [protoc](http://google.github.io/proto-lens/installing-protoc.html) installed and available in your path.
46+
47+
Next, 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+
```
50+
mage protobuf
51+
```
52+
53+
### Changing `generic_*.go` files in the `data` package
54+
55+
Currently [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+
59+
We use Go modules for managing Go dependencies. After you've updated/modified modules dependencies, please run `go mod tidy` to cleanup dependencies.

0 commit comments

Comments
 (0)