From 0f0a53fbbb999eeb7333cd04b8e02a4117e0f878 Mon Sep 17 00:00:00 2001 From: Ryan McKinley Date: Tue, 31 Jan 2023 14:54:22 -0800 Subject: [PATCH] Schemas: Add description to kinds metadata (#62638) * add description to kinds * omit empty --- kinds/dashboard/dashboard_kind.cue | 5 +++-- kinds/librarypanel/librarypanel_kind.cue | 5 +++-- kinds/playlist/playlist_kind.cue | 5 +++-- kinds/preferences/preferences_kind.cue | 5 +++-- kinds/publicdashboard/public_dashboard_kind.cue | 5 +++-- kinds/serviceaccount/serviceaccount_kind.cue | 5 +++-- kinds/team/team_kind.cue | 5 +++-- pkg/kindsys/kindcats.cue | 11 +++++++++++ pkg/kindsys/props.go | 1 + pkg/kindsys/report.json | 7 +++++++ 10 files changed, 40 insertions(+), 14 deletions(-) diff --git a/kinds/dashboard/dashboard_kind.cue b/kinds/dashboard/dashboard_kind.cue index 84f18a234c4..bcb8943df5f 100644 --- a/kinds/dashboard/dashboard_kind.cue +++ b/kinds/dashboard/dashboard_kind.cue @@ -2,8 +2,9 @@ package kind import "strings" -name: "Dashboard" -maturity: "experimental" +name: "Dashboard" +maturity: "experimental" +description: "A Grafana dashboard." lineage: seqs: [ { diff --git a/kinds/librarypanel/librarypanel_kind.cue b/kinds/librarypanel/librarypanel_kind.cue index 6a9cbd5c897..e097dddd5f0 100644 --- a/kinds/librarypanel/librarypanel_kind.cue +++ b/kinds/librarypanel/librarypanel_kind.cue @@ -2,8 +2,9 @@ package kind import "strings" -name: "LibraryPanel" -maturity: "experimental" +name: "LibraryPanel" +maturity: "experimental" +description: "A standalone panel" lineage: seqs: [ { diff --git a/kinds/playlist/playlist_kind.cue b/kinds/playlist/playlist_kind.cue index 2dbb7ed2942..0bf700d3a66 100644 --- a/kinds/playlist/playlist_kind.cue +++ b/kinds/playlist/playlist_kind.cue @@ -1,7 +1,8 @@ package kind -name: "Playlist" -maturity: "merged" +name: "Playlist" +maturity: "merged" +description: "A playlist is a series of dashboards that is automatically rotated in the browser, on a configurable interval." lineage: seqs: [ { diff --git a/kinds/preferences/preferences_kind.cue b/kinds/preferences/preferences_kind.cue index 1e4be8b9b82..1e140035e66 100644 --- a/kinds/preferences/preferences_kind.cue +++ b/kinds/preferences/preferences_kind.cue @@ -1,7 +1,8 @@ package kind -name: "Preferences" -maturity: "merged" +name: "Preferences" +maturity: "merged" +description: "The user or team frontend preferences" lineage: seqs: [ { diff --git a/kinds/publicdashboard/public_dashboard_kind.cue b/kinds/publicdashboard/public_dashboard_kind.cue index 1e960fa7cb4..71f2494fc46 100644 --- a/kinds/publicdashboard/public_dashboard_kind.cue +++ b/kinds/publicdashboard/public_dashboard_kind.cue @@ -1,7 +1,8 @@ package kind -name: "PublicDashboard" -maturity: "merged" +name: "PublicDashboard" +maturity: "merged" +description: "Public dashboard configuration" lineage: seqs: [ { diff --git a/kinds/serviceaccount/serviceaccount_kind.cue b/kinds/serviceaccount/serviceaccount_kind.cue index afa0f818394..fc49a346611 100644 --- a/kinds/serviceaccount/serviceaccount_kind.cue +++ b/kinds/serviceaccount/serviceaccount_kind.cue @@ -1,7 +1,8 @@ package kind -name: "ServiceAccount" -maturity: "merged" +name: "ServiceAccount" +maturity: "merged" +description: "system account" lineage: seqs: [ { diff --git a/kinds/team/team_kind.cue b/kinds/team/team_kind.cue index 73cbc9b761d..8146ddc95ca 100644 --- a/kinds/team/team_kind.cue +++ b/kinds/team/team_kind.cue @@ -1,7 +1,8 @@ package kind -name: "Team" -maturity: "merged" +name: "Team" +maturity: "merged" +description: "A team is a named grouping of Grafana users to which access control rules may be assigned." lineage: seqs: [ { diff --git a/pkg/kindsys/kindcats.cue b/pkg/kindsys/kindcats.cue index cdbe09f5946..afc728b30fd 100644 --- a/pkg/kindsys/kindcats.cue +++ b/pkg/kindsys/kindcats.cue @@ -79,6 +79,14 @@ _sharedKind: { maturity: *"merged" | "experimental" } +// properties shared by all kinds that represent a complete object from root (i.e., not composable) +_rootKind: { + // description is a brief narrative description of the nature and purpose of the kind. + // The contents of this field is shown to end users. Prefer clear, concise wording + // with minimal jargon. + description: nonEmptyString +} + // Maturity indicates the how far a given kind definition is in its initial // journey. Mature kinds still evolve, but with guarantees about compatibility. Maturity: "merged" | "experimental" | "stable" | "mature" @@ -88,7 +96,10 @@ Maturity: "merged" | "experimental" | "stable" | "mature" // and datasources, are represented as core kinds. Core: S=close({ _sharedKind + _rootKind lineage: { name: S.machineName } lineageIsGroup: false }) + +nonEmptyString: string & strings.MinRunes(1) diff --git a/pkg/kindsys/props.go b/pkg/kindsys/props.go index c289094d270..9cd507db447 100644 --- a/pkg/kindsys/props.go +++ b/pkg/kindsys/props.go @@ -10,6 +10,7 @@ type CommonProperties struct { PluralMachineName string `json:"pluralMachineName"` LineageIsGroup bool `json:"lineageIsGroup"` Maturity Maturity `json:"maturity"` + Description string `json:"description,omitempty"` } // CoreProperties represents the static properties in the definition of a diff --git a/pkg/kindsys/report.json b/pkg/kindsys/report.json index af9a9e66874..59495972d8c 100644 --- a/pkg/kindsys/report.json +++ b/pkg/kindsys/report.json @@ -283,6 +283,7 @@ 0, 0 ], + "description": "A Grafana dashboard.", "grafanaMaturityCount": 139, "lineageIsGroup": false, "links": { @@ -819,6 +820,7 @@ 0, 0 ], + "description": "A standalone panel", "grafanaMaturityCount": 10, "lineageIsGroup": false, "links": { @@ -1181,6 +1183,7 @@ 0, 0 ], + "description": "A playlist is a series of dashboards that is automatically rotated in the browser, on a configurable interval.", "grafanaMaturityCount": 0, "lineageIsGroup": false, "links": { @@ -1251,6 +1254,7 @@ 0, 0 ], + "description": "The user or team frontend preferences", "grafanaMaturityCount": 0, "lineageIsGroup": false, "links": { @@ -1321,6 +1325,7 @@ 0, 0 ], + "description": "Public dashboard configuration", "grafanaMaturityCount": 0, "lineageIsGroup": false, "links": { @@ -1389,6 +1394,7 @@ 0, 0 ], + "description": "system account", "grafanaMaturityCount": 9, "lineageIsGroup": false, "links": { @@ -1509,6 +1515,7 @@ 0, 0 ], + "description": "A team is a named grouping of Grafana users to which access control rules may be assigned.", "grafanaMaturityCount": 7, "lineageIsGroup": false, "links": {