From ea2500c7c3d064b2caad875db41a666d482c3968 Mon Sep 17 00:00:00 2001 From: Jocelyn Collado-Kuri Date: Tue, 23 Jun 2026 13:39:00 -0600 Subject: [PATCH 1/5] add docs for publishing schema --- dsconfig/PUBLISH-SCHEMA.md | 94 ++++++++++++++++++++++++++++++++++++++ dsconfig/README.md | 3 ++ 2 files changed, 97 insertions(+) create mode 100644 dsconfig/PUBLISH-SCHEMA.md diff --git a/dsconfig/PUBLISH-SCHEMA.md b/dsconfig/PUBLISH-SCHEMA.md new file mode 100644 index 0000000..6074817 --- /dev/null +++ b/dsconfig/PUBLISH-SCHEMA.md @@ -0,0 +1,94 @@ +#### Change 1 : Add `pkg/schema/dsconfig.json` + +add the `dsconfig.json` file to the specified location. ( either manually authored / copy the already baselined ones from plugin-ui. + +```json +{ + "$schema": "https://raw.githubusercontent.com/grafana/dsconfig/refs/heads/main/dsconfig/schema.json", + "schemaVersion": "v1", + "pluginType": "grafana-athena-datasource", + "pluginName": "Amazon Athena", + .... +} +``` + +### Change 2 : Add `pkg/schema/dsconfig_test.go` + +```go +package schema_test + +import ( + _ "embed" + "testing" + + "github.com/grafana/athena-datasource/pkg/athena/models" + "github.com/grafana/dsconfig/schema" +) + +//go:embed dsconfig.json +var configSchemaJSON []byte + +//go:generate go test -run TestPlugin -generateArtifacts +func TestPlugin(t *testing.T) { + schema.RunPluginTests(t, schema.PluginUnderTest{ + ID: "grafana-athena-datasource", + ConfigSchemaJSON: configSchemaJSON, + SettingsJSONModel: models.AthenaDataSourceSettings{}, + SecureKeys: []string{"accessKey", "secretKey", "sessionToken", "proxyPassword"}, + }) +} +``` + +### Change 3 : Add / Update `webpack.config.ts` in the root folder + +Add/Update the `webpack.config.ts` in the root folder + +```ts +import { type Configuration } from "webpack"; +import { merge } from "webpack-merge"; +import CopyWebpackPlugin from "copy-webpack-plugin"; +import grafanaConfig, { type Env } from "./.config/webpack/webpack.config"; + +const config = async (env: Env): Promise => { + const baseConfig = await grafanaConfig(env); + return merge(baseConfig, { + plugins: [ + new CopyWebpackPlugin({ + patterns: [ + { + from: "../pkg/schema/dsconfig.json", + to: "./schema/dsconfig.json", + noErrorOnMissing: true, + }, + { + from: "../pkg/schema/schema.gen.json", + to: "./schema/v0alpha1.json", + noErrorOnMissing: true, + }, + { + from: "../pkg/schema/settings.gen.json", + to: "./schema/v0alpha1/settings.json", + noErrorOnMissing: true, + }, + { + from: "../pkg/schema/settings.examples.gen.json", + to: "./schema/v0alpha1/settings.examples.json", + noErrorOnMissing: true, + }, + ], + }), + ], + }); +}; + +export default config; +``` + +### Change 4 : Update the package.json script + +```diff +- "build": "webpack -c ./.config/webpack/webpack.config.ts --env production", ++ "build": "webpack -c ./webpack.config.ts --env production", +- "dev": "webpack -w -c ./.config/webpack/webpack.config.ts --env development", ++ "dev": "webpack -w -c ./webpack.config.ts --env development", +``` diff --git a/dsconfig/README.md b/dsconfig/README.md index d2595de..b5e60b5 100644 --- a/dsconfig/README.md +++ b/dsconfig/README.md @@ -696,3 +696,6 @@ Virtual fields are not stored. They derive a value from other fields for UI logi | 5 | How should `secureJsonFields` (read-side boolean map) be modeled in the schema or SDK output? | | 6 | Should validation rule evaluation order, short-circuit behavior, or severity levels be defined? | | 7 | Should groups enforce completeness? (every field must belong to at least one group) | + + +Once done generating your datasource's `dsconfig.json`, go to [PUBLISH-SCHEMA.md](PUBLISH-SCHEMA.md) \ No newline at end of file From 8b8415d89959842494d3775902d03615d2adcc00 Mon Sep 17 00:00:00 2001 From: Jocelyn Collado-Kuri Date: Tue, 23 Jun 2026 15:08:51 -0600 Subject: [PATCH 2/5] expand publish schema instructions --- dsconfig/PUBLISH-SCHEMA.md | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/dsconfig/PUBLISH-SCHEMA.md b/dsconfig/PUBLISH-SCHEMA.md index 6074817..5a29116 100644 --- a/dsconfig/PUBLISH-SCHEMA.md +++ b/dsconfig/PUBLISH-SCHEMA.md @@ -12,7 +12,17 @@ add the `dsconfig.json` file to the specified location. ( either manually author } ``` -### Change 2 : Add `pkg/schema/dsconfig_test.go` +#### Change 2: Install dependencies +If you have not already, run: +``` +go get github.com/grafana/dsconfig/schema +``` + +#### Change 3: IF one does not exist yet, create a `pkg/schema/models/settings.go` + +Use this file to define the go representation of your given datasource settings. + +#### Change 4 : Add `pkg/schema/dsconfig_test.go` ```go package schema_test @@ -39,7 +49,7 @@ func TestPlugin(t *testing.T) { } ``` -### Change 3 : Add / Update `webpack.config.ts` in the root folder +### Change 5 : Add / Update `webpack.config.ts` in the root folder Add/Update the `webpack.config.ts` in the root folder @@ -84,7 +94,7 @@ const config = async (env: Env): Promise => { export default config; ``` -### Change 4 : Update the package.json script +### Change 6 : Update the package.json script ```diff - "build": "webpack -c ./.config/webpack/webpack.config.ts --env production", From a483e7fa523461d881806aeda776a2e72f3e13c7 Mon Sep 17 00:00:00 2001 From: Jocelyn Collado-Kuri Date: Wed, 24 Jun 2026 07:52:57 -0600 Subject: [PATCH 3/5] add more instructions on how to run scripts --- dsconfig/PUBLISH-SCHEMA.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/dsconfig/PUBLISH-SCHEMA.md b/dsconfig/PUBLISH-SCHEMA.md index 5a29116..67cee8e 100644 --- a/dsconfig/PUBLISH-SCHEMA.md +++ b/dsconfig/PUBLISH-SCHEMA.md @@ -1,3 +1,5 @@ +## Setting up your files + #### Change 1 : Add `pkg/schema/dsconfig.json` add the `dsconfig.json` file to the specified location. ( either manually authored / copy the already baselined ones from plugin-ui. @@ -13,7 +15,9 @@ add the `dsconfig.json` file to the specified location. ( either manually author ``` #### Change 2: Install dependencies + If you have not already, run: + ``` go get github.com/grafana/dsconfig/schema ``` @@ -102,3 +106,9 @@ export default config; - "dev": "webpack -w -c ./.config/webpack/webpack.config.ts --env development", + "dev": "webpack -w -c ./webpack.config.ts --env development", ``` + +## File generation + +1. run `generate go test -run TestPlugin -generateArtifacts` this will generate all the necessary artifacts for the configuration schema + +2. To make sure everything looks right run the test that you created above under `dsconfig_test.go`. This will run tests and compare the config schema against the datasource's declared go types to make sure it matches. From a28952e8e5bc00086aa075760116aadf7fa995fd Mon Sep 17 00:00:00 2001 From: Jocelyn Collado-Kuri Date: Wed, 24 Jun 2026 12:06:18 -0600 Subject: [PATCH 4/5] add instructions on releasing new version of dsconfig --- README.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/README.md b/README.md index d782214..416039c 100644 --- a/README.md +++ b/README.md @@ -2,3 +2,15 @@ > [!WARNING] > This is an experimental project and still under active development + +# Releasing a new dsconfig SDK version + +Go to https://github.com/grafana/dsconfig/tags to verify the latest version that has been published. + +From the root folder run, with the above version bumped: + +`git tag dsconfig/v && git tag schema/v` + +Then push the tags: + +`git push --tags` From 071c740c577c77937fe5723e11c4a84bb7a9cd81 Mon Sep 17 00:00:00 2001 From: Jocelyn Collado-Kuri Date: Wed, 24 Jun 2026 13:12:55 -0600 Subject: [PATCH 5/5] update instructions --- README.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 416039c..631f0f3 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,14 @@ Go to https://github.com/grafana/dsconfig/tags to verify the latest version that has been published. -From the root folder run, with the above version bumped: + +From the root folder: + +Pull the latest changes into your local main branch + +`git checkout main && git pull` + +Bump the version you saw above `git tag dsconfig/v && git tag schema/v`