You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+48Lines changed: 48 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -10,3 +10,51 @@ Thank you for your interest in contributing to this repository. We are glad you
10
10
## Next steps
11
11
12
12
-[Set up your development environment](./docs/developer-guide.md)
13
+
14
+
## Data source configuration schema
15
+
16
+
[`pkg/schema/dsconfig.json`](./pkg/schema/dsconfig.json) describes the plugin's configuration fields, storage locations, validation rules, UI hints, and instructions for automation. Edit this file when changing the configuration schema.
17
+
18
+
The format and shared tooling come from [`grafana/dsconfig`](https://github.com/grafana/dsconfig/tree/main/dsconfig):
19
+
20
+
-[README](https://github.com/grafana/dsconfig/tree/main/dsconfig#readme): concepts and examples.
21
+
-[Schema reference](https://github.com/grafana/dsconfig/blob/main/dsconfig/schema.md): field properties and validation rules.
22
+
-[Publishing guide](https://github.com/grafana/dsconfig/blob/main/dsconfig/PUBLISH-SCHEMA.md): generation and packaging setup.
Do not edit `.gen.json` files by hand. The generator uses the version of `github.com/grafana/dsconfig/schema` pinned in `go.mod`. The `$schema` URL in `dsconfig.json` identifies the JSON Schema used to validate the authoring format; review that pin when upgrading dsconfig.
36
+
37
+
### Updating configuration
38
+
39
+
1. Update `pkg/schema/dsconfig.json`, including any relevant groups, validation rules, and instructions. Keep stored fields consistent with the configuration editor and backend. A virtual field represents a UI control rather than a saved setting.
40
+
2. Update `models.Settings` and its JSON tags where needed. For secrets, update `models.SecureJsonDataKeys` and the code that reads `DecryptedSecureJSONData` instead of adding a normal JSON setting. Preserve support for existing configurations when changing types, including string and numeric GitHub App IDs.
41
+
3. Update `SettingsExamples` in `pkg/schema/dsconfig_test.go` when the configuration examples change. The existing examples cover personal access tokens, GitHub Apps, Enterprise Cloud, and Enterprise Server. Use placeholders, never real credentials.
42
+
4. Regenerate the artifacts from the repository root:
43
+
44
+
```bash
45
+
go generate ./pkg/schema/...
46
+
```
47
+
48
+
5. Verify schema consistency and backend parsing:
49
+
50
+
```bash
51
+
go test ./pkg/schema/... ./pkg/models/... -count=1
52
+
```
53
+
54
+
6. Review and commit any generated changes alongside the source changes. An instructions-only edit may leave the generated artifacts unchanged.
55
+
56
+
The `go:generate` directive in `dsconfig_test.go` runs `go test -run TestPlugin -generateArtifacts`. Normal test runs check the artifacts without regenerating them. A `SchemaArtifactInSync` failure means regeneration is needed; key, type, or secret consistency failures require correcting the schema or Go declarations.
57
+
58
+
### Building the published files
59
+
60
+
Run `npm run build` to copy the source schema and generated artifacts into the plugin's `dist/schema/` directory via `webpack.config.ts`. This packages the files; it does not replace the Go generation step. Grafana serves the source schema at `/public/plugins/grafana-github-datasource/schema/dsconfig.json` once that build is installed.
0 commit comments