From 0e8ef44756e466a291f030351c3f8b68643bb1d7 Mon Sep 17 00:00:00 2001 From: Christian Richter Date: Mon, 28 Nov 2022 18:04:01 +0100 Subject: [PATCH 1/7] Add depreaction annotations to variables Signed-off-by: Christian Richter --- .../unreleased/add-deprecation-annotation.md | 14 ++++ docs/helpers/adoc-generator.go.tmpl | 84 ++++++++++++++++--- docs/templates/ADOC.tmpl | 43 ++++++++-- 3 files changed, 121 insertions(+), 20 deletions(-) create mode 100644 changelog/unreleased/add-deprecation-annotation.md diff --git a/changelog/unreleased/add-deprecation-annotation.md b/changelog/unreleased/add-deprecation-annotation.md new file mode 100644 index 0000000000..0c8542f911 --- /dev/null +++ b/changelog/unreleased/add-deprecation-annotation.md @@ -0,0 +1,14 @@ +Enhancement: Add deprecation annotation + +We have added the ability to annotate variables in case of deprecations: + +Example: + +`services/nats/pkg/config/config.go` + +``` +Host string `yaml:"host" env:"NATS_HOST_ADDRESS,NATS_NATS_HOST" desc:"Bind address." deprecationVersion:"1.6.2" removalVersion:"1.7.5" deprecationInfo:"the name is ugly" deprecationReplacement:"NATS_HOST_ADDRESS"` +``` + +https://github.com/owncloud/ocis/issues/3917 +https://github.com/owncloud/ocis/pull/5143 diff --git a/docs/helpers/adoc-generator.go.tmpl b/docs/helpers/adoc-generator.go.tmpl index f8ff5701dc..2bc94b3a55 100644 --- a/docs/helpers/adoc-generator.go.tmpl +++ b/docs/helpers/adoc-generator.go.tmpl @@ -20,12 +20,22 @@ type ConfigField struct { DefaultValue string Type string Description string - VersionInfo string + VersionInfo string + IsDeprecated bool +} + +type DeprecationField struct { + DeprecationVersion string + DeprecationInfo string + DeprecationReplacement string + RemovalVersion string } type templateData struct { - ExtensionName string - Fields []ConfigField + ExtensionName string + Fields []ConfigField + Deprecations []DeprecationField + HasDeprecations bool } func main() { @@ -39,6 +49,7 @@ replacer := strings.NewReplacer( "/pkg/config/defaults", "", ) var fields []ConfigField +var deprecations []DeprecationField var targetFile *os.File tpl := template.Must(template.New("").Parse(string(content))) @@ -50,8 +61,13 @@ m := map[string]interface{}{ targetFolder := "../../docs/services/_includes/adoc/" for pkg, conf := range m { - fields = GetAnnotatedVariables(conf) - if len(fields) > 0 { + fields, deprecations = GetAnnotatedVariables(conf) + var hasDeprecations bool + if len(deprecations) > 0 { + hasDeprecations = true + } + + if len(fields) > 0 || len(deprecations) > 0 { fmt.Printf("... %s\n", pkg) targetFile, err = os.Create(filepath.Join(targetFolder, replacer.Replace(pkg) + "_configvars.adoc")) if err != nil { @@ -62,6 +78,8 @@ m := map[string]interface{}{ td := templateData{ ExtensionName: replacer.Replace(pkg), Fields: fields, + Deprecations: deprecations, + HasDeprecations: hasDeprecations , } if err := tpl.Execute(targetFile, td); err != nil { log.Fatalf("Failed to execute template: %s", err) @@ -71,11 +89,12 @@ m := map[string]interface{}{ fmt.Println("done") } -func GetAnnotatedVariables(s interface{}) []ConfigField { +func GetAnnotatedVariables(s interface{}) ([]ConfigField, []DeprecationField) { t := reflect.TypeOf(s) v := reflect.ValueOf(s) var fields []ConfigField + var deprecations []DeprecationField for i := 0; i < t.NumField(); i++ { field := t.Field(i) value := v.Field(i) @@ -84,10 +103,33 @@ func GetAnnotatedVariables(s interface{}) []ConfigField { default: desc := field.Tag.Get("desc") env, ok := field.Tag.Lookup("env") + isDeprecated := false if !ok { continue } - v := fmt.Sprintf("%v", value.Interface()) + deprecationVersion, ok := field.Tag.Lookup("deprecationVersion") + if !ok { + deprecationVersion = "" + } + removalVersion, ok := field.Tag.Lookup("removalVersion") + if !ok { + removalVersion = "" + } + deprecationInfo, ok := field.Tag.Lookup("deprecationInfo") + if !ok { + deprecationInfo = "" + } + deprecationReplacement, ok := field.Tag.Lookup("deprecationReplacement") + if !ok { + deprecationReplacement = "" + } + if deprecationVersion != "" || + removalVersion != "" || + deprecationInfo != "" || + deprecationReplacement != "" { + isDeprecated = true + } + v := fmt.Sprintf("%v", value.Interface()) td := strings.Split(env, ";") // re := regexp.MustCompile(`^(https?:\/\/)`) // v = re.ReplaceAllString(v,"\\$1") @@ -99,18 +141,38 @@ func GetAnnotatedVariables(s interface{}) []ConfigField { if typeName == "" { typeName = value.Type().String() } - fields = append(fields, ConfigField{EnvVars: td, DefaultValue: v, Description: desc, Type: typeName}) + fields = append(fields, + ConfigField{ + EnvVars: td, + DefaultValue: v, + Description: desc, + Type: typeName, + IsDeprecated: isDeprecated, + }) + if isDeprecated { + deprecations = append(deprecations, + DeprecationField{ + DeprecationVersion: deprecationVersion, + DeprecationInfo: deprecationInfo, + DeprecationReplacement: deprecationReplacement, + RemovalVersion: removalVersion, + }) + } case reflect.Ptr: // PolicySelectors in the Proxy are being skipped atm // they are not configurable via env vars, if that changes // they are probably added to the Sanitize() function // and this should not be an issue then if !value.IsZero() && value.Elem().CanInterface() { - fields = append(fields, GetAnnotatedVariables(value.Elem().Interface())...) + f, d := GetAnnotatedVariables(value.Elem().Interface()) + fields = append(fields, f...) + deprecations = append(deprecations, d...) } case reflect.Struct: - fields = append(fields, GetAnnotatedVariables(value.Interface())...) + f, d := GetAnnotatedVariables(value.Interface()) + fields = append(fields, f...) + deprecations = append(deprecations, d...) } } - return fields + return fields, deprecations } diff --git a/docs/templates/ADOC.tmpl b/docs/templates/ADOC.tmpl index 75b8d182f7..4f7f0b3221 100644 --- a/docs/templates/ADOC.tmpl +++ b/docs/templates/ADOC.tmpl @@ -1,17 +1,43 @@ +// set the attribute to true or leave empty, true without any quotes. +:show-deprecation: {{ .HasDeprecations }} + +ifeval::[{show-deprecation} == true] +[[deprecation-note]] +[caption=] +[width="100%",cols="~,~,~,~",options="header"] +| === | +| Deprecation Version | +| Removal Version | +| Deprecation Info | +| Deprecation Replacment | + +{{- range .Deprecations }} +| {{ .DeprecationVersion }} +| {{ .RemovalVersion }} +| {{ .DeprecationInfo }} +| {{ .DeprecationReplacement }} +| === +{{- end }} +endif::[] + [caption=] .Environment variables for the {{ .ExtensionName }} service [width="100%",cols="~,~,~,~",options="header"] -|=== -| Name -| Type -| Default Value -| Description +| === | +| Name | +| Type | +| Default Value | +| Description | {{- range .Fields}} -| {{- range $i, $value := .EnvVars }}{{- if $i }} + +:is-deprecated: {{ .IsDeprecated }} +| {{- range $i, $value := .EnvVars }}{{- if $i }} + | {{ end -}} `{{- $value }}` -{{- end }} +{{- end }} + +ifeval::[{is-deprecated} == true] +xref:deprecation-note[Deprecation Note] +endif::[] a| [subs=-attributes] ++{{.Type}} ++ a| [subs=-attributes] @@ -20,6 +46,5 @@ a| [subs=-attributes] {{.Description}} {{- end }} -|=== +| === | -Since Version: `+` added, `-` deprecated From c07dafabbd99eb1d5e87c02cfdbc77d310935785 Mon Sep 17 00:00:00 2001 From: mmattel Date: Mon, 28 Nov 2022 23:10:43 +0100 Subject: [PATCH 2/7] update adoc.tmpl --- docs/templates/ADOC.tmpl | 34 +++++++++++++++++++--------------- 1 file changed, 19 insertions(+), 15 deletions(-) diff --git a/docs/templates/ADOC.tmpl b/docs/templates/ADOC.tmpl index 4f7f0b3221..183c4bf729 100644 --- a/docs/templates/ADOC.tmpl +++ b/docs/templates/ADOC.tmpl @@ -1,43 +1,47 @@ // set the attribute to true or leave empty, true without any quotes. + :show-deprecation: {{ .HasDeprecations }} ifeval::[{show-deprecation} == true] + [[deprecation-note]] [caption=] [width="100%",cols="~,~,~,~",options="header"] -| === | -| Deprecation Version | -| Removal Version | -| Deprecation Info | -| Deprecation Replacment | +|=== +| Deprecation Version +| Removal Version +| Deprecation Info +| Deprecation Replacment {{- range .Deprecations }} | {{ .DeprecationVersion }} | {{ .RemovalVersion }} | {{ .DeprecationInfo }} | {{ .DeprecationReplacement }} -| === {{- end }} +|=== + endif::[] [caption=] .Environment variables for the {{ .ExtensionName }} service [width="100%",cols="~,~,~,~",options="header"] -| === | -| Name | -| Type | -| Default Value | -| Description | +|=== +| Name +| Type +| Default Value +| Description {{- range .Fields}} -:is-deprecated: {{ .IsDeprecated }} -| {{- range $i, $value := .EnvVars }}{{- if $i }} + | + +a| {{- range $i, $value := .EnvVars }}{{- if $i }} + {{ end -}} `{{- $value }}` {{- end }} + +:is-deprecated: {{ .IsDeprecated }} ifeval::[{is-deprecated} == true] xref:deprecation-note[Deprecation Note] -endif::[] +endif::[] a| [subs=-attributes] ++{{.Type}} ++ a| [subs=-attributes] @@ -46,5 +50,5 @@ a| [subs=-attributes] {{.Description}} {{- end }} -| === | +|=== From e3043a7e7b2be1b13b78175ac34a260ad2abe7e2 Mon Sep 17 00:00:00 2001 From: Christian Richter Date: Tue, 29 Nov 2022 10:49:09 +0100 Subject: [PATCH 3/7] Incorporate Requested Changes Signed-off-by: Christian Richter --- docs/helpers/adoc-generator.go.tmpl | 20 ++++---------------- 1 file changed, 4 insertions(+), 16 deletions(-) diff --git a/docs/helpers/adoc-generator.go.tmpl b/docs/helpers/adoc-generator.go.tmpl index 2bc94b3a55..4cbdced667 100644 --- a/docs/helpers/adoc-generator.go.tmpl +++ b/docs/helpers/adoc-generator.go.tmpl @@ -107,22 +107,10 @@ func GetAnnotatedVariables(s interface{}) ([]ConfigField, []DeprecationField) { if !ok { continue } - deprecationVersion, ok := field.Tag.Lookup("deprecationVersion") - if !ok { - deprecationVersion = "" - } - removalVersion, ok := field.Tag.Lookup("removalVersion") - if !ok { - removalVersion = "" - } - deprecationInfo, ok := field.Tag.Lookup("deprecationInfo") - if !ok { - deprecationInfo = "" - } - deprecationReplacement, ok := field.Tag.Lookup("deprecationReplacement") - if !ok { - deprecationReplacement = "" - } + deprecationVersion, _ := field.Tag.Lookup("deprecationVersion") + removalVersion, _ := field.Tag.Lookup("removalVersion") + deprecationInfo, _ := field.Tag.Lookup("deprecationInfo") + deprecationReplacement, _ := field.Tag.Lookup("deprecationReplacement") if deprecationVersion != "" || removalVersion != "" || deprecationInfo != "" || From a88af41ae2dd3e95f98fe0b9c802e92abefff243 Mon Sep 17 00:00:00 2001 From: Christian Richter Date: Tue, 29 Nov 2022 10:52:06 +0100 Subject: [PATCH 4/7] Move conditional for deprecation Link into go template Signed-off-by: Christian Richter --- docs/helpers/adoc-generator.go.tmpl | 28 ++++++++++++++-------------- docs/templates/ADOC.tmpl | 5 +---- 2 files changed, 15 insertions(+), 18 deletions(-) diff --git a/docs/helpers/adoc-generator.go.tmpl b/docs/helpers/adoc-generator.go.tmpl index 4cbdced667..7ab267dd2c 100644 --- a/docs/helpers/adoc-generator.go.tmpl +++ b/docs/helpers/adoc-generator.go.tmpl @@ -16,12 +16,12 @@ import ( {{- end}}) type ConfigField struct { - EnvVars []string - DefaultValue string - Type string - Description string - VersionInfo string - IsDeprecated bool + EnvVars []string + DefaultValue string + Type string + Description string + VersionInfo string + DeprecationLink string } type DeprecationField struct { @@ -103,7 +103,7 @@ func GetAnnotatedVariables(s interface{}) ([]ConfigField, []DeprecationField) { default: desc := field.Tag.Get("desc") env, ok := field.Tag.Lookup("env") - isDeprecated := false + deprecationLink := "" if !ok { continue } @@ -115,7 +115,7 @@ func GetAnnotatedVariables(s interface{}) ([]ConfigField, []DeprecationField) { removalVersion != "" || deprecationInfo != "" || deprecationReplacement != "" { - isDeprecated = true + deprecationLink = "xref:deprecation-note[Deprecation Note]" } v := fmt.Sprintf("%v", value.Interface()) td := strings.Split(env, ";") @@ -131,13 +131,13 @@ func GetAnnotatedVariables(s interface{}) ([]ConfigField, []DeprecationField) { } fields = append(fields, ConfigField{ - EnvVars: td, - DefaultValue: v, - Description: desc, - Type: typeName, - IsDeprecated: isDeprecated, + EnvVars: td, + DefaultValue: v, + Description: desc, + Type: typeName, + DeprecationLink: deprecationLink, }) - if isDeprecated { + if deprecationLink != "" { deprecations = append(deprecations, DeprecationField{ DeprecationVersion: deprecationVersion, diff --git a/docs/templates/ADOC.tmpl b/docs/templates/ADOC.tmpl index 183c4bf729..c5643c9b3c 100644 --- a/docs/templates/ADOC.tmpl +++ b/docs/templates/ADOC.tmpl @@ -38,10 +38,7 @@ a| {{- range $i, $value := .EnvVars }}{{- if $i }} + {{ end -}} `{{- $value }}` {{- end }} + -:is-deprecated: {{ .IsDeprecated }} -ifeval::[{is-deprecated} == true] -xref:deprecation-note[Deprecation Note] -endif::[] +{{ .DeprecationLink }} a| [subs=-attributes] ++{{.Type}} ++ a| [subs=-attributes] From 0a88fc47c8074eee8de8fd1b7465ffaed7dd4ad4 Mon Sep 17 00:00:00 2001 From: Christian Richter Date: Tue, 29 Nov 2022 11:08:57 +0100 Subject: [PATCH 5/7] Rearrange adoc deprecation table Signed-off-by: Christian Richter --- docs/templates/ADOC.tmpl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/templates/ADOC.tmpl b/docs/templates/ADOC.tmpl index c5643c9b3c..ca6c7a5ce7 100644 --- a/docs/templates/ADOC.tmpl +++ b/docs/templates/ADOC.tmpl @@ -8,9 +8,9 @@ ifeval::[{show-deprecation} == true] [caption=] [width="100%",cols="~,~,~,~",options="header"] |=== +| Deprecation Info | Deprecation Version | Removal Version -| Deprecation Info | Deprecation Replacment {{- range .Deprecations }} From e6d4e765d2590427a61c717b5d7a85930ff21ccd Mon Sep 17 00:00:00 2001 From: Christian Richter Date: Tue, 29 Nov 2022 11:12:06 +0100 Subject: [PATCH 6/7] switch cols Signed-off-by: Christian Richter --- docs/templates/ADOC.tmpl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/templates/ADOC.tmpl b/docs/templates/ADOC.tmpl index ca6c7a5ce7..496a58ea78 100644 --- a/docs/templates/ADOC.tmpl +++ b/docs/templates/ADOC.tmpl @@ -14,9 +14,9 @@ ifeval::[{show-deprecation} == true] | Deprecation Replacment {{- range .Deprecations }} +| {{ .DeprecationInfo }} | {{ .DeprecationVersion }} | {{ .RemovalVersion }} -| {{ .DeprecationInfo }} | {{ .DeprecationReplacement }} {{- end }} |=== From 422bc4e65abe261de634d7de2f90c31a6bbd0078 Mon Sep 17 00:00:00 2001 From: Christian Richter Date: Tue, 29 Nov 2022 11:13:32 +0100 Subject: [PATCH 7/7] add missing blank line Signed-off-by: Christian Richter --- docs/templates/ADOC.tmpl | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/templates/ADOC.tmpl b/docs/templates/ADOC.tmpl index 496a58ea78..73d54b53f4 100644 --- a/docs/templates/ADOC.tmpl +++ b/docs/templates/ADOC.tmpl @@ -14,6 +14,7 @@ ifeval::[{show-deprecation} == true] | Deprecation Replacment {{- range .Deprecations }} + | {{ .DeprecationInfo }} | {{ .DeprecationVersion }} | {{ .RemovalVersion }}