Merge pull request #5143 from dragonchaser/add-deprecation-for-variables

Add depreaction annotations to variables

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

docs/helpers/adoc-generator.go.tmpl

@@ -16,16 +16,26 @@ import (
     {{- end}})
 
 type ConfigField struct {
-	EnvVars      []string
-	DefaultValue string
-	Type         string
-	Description  string
-	VersionInfo	 string
+	EnvVars         []string
+	DefaultValue    string
+	Type            string
+	Description     string
+	VersionInfo     string
+	DeprecationLink string
+}
+
+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,21 @@ func GetAnnotatedVariables(s interface{}) []ConfigField {
 		default:
 			desc := field.Tag.Get("desc")
 			env, ok := field.Tag.Lookup("env")
+			deprecationLink := ""
 			if !ok {
 				continue
 			}
-			v := fmt.Sprintf("%v", value.Interface())			
+			deprecationVersion, _ := field.Tag.Lookup("deprecationVersion")
+			removalVersion, _ := field.Tag.Lookup("removalVersion")
+			deprecationInfo, _ := field.Tag.Lookup("deprecationInfo")
+			deprecationReplacement, _ := field.Tag.Lookup("deprecationReplacement")
+			if deprecationVersion != "" ||
+				removalVersion != "" ||
+				deprecationInfo != "" ||
+				deprecationReplacement != "" {
+				deprecationLink = "xref:deprecation-note[Deprecation Note]"
+			}
+			v := fmt.Sprintf("%v", value.Interface())
 			td := strings.Split(env, ";")
 			// re := regexp.MustCompile(`^(https?:\/\/)`)
 			// v = re.ReplaceAllString(v,"\\$1")
@@ -99,18 +129,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,
+					DeprecationLink: deprecationLink,
+				})
+			if deprecationLink != "" {
+				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
 }

docs/templates/ADOC.tmpl

@@ -1,3 +1,29 @@
+// 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 Info
+| Deprecation Version
+| Removal Version
+| Deprecation Replacment
+
+{{- range .Deprecations }}
+
+| {{ .DeprecationInfo }}
+| {{ .DeprecationVersion }}
+| {{ .RemovalVersion }}
+| {{ .DeprecationReplacement }}
+{{- end }}
+|===
+
+endif::[]
+
 [caption=]
 .Environment variables for the {{ .ExtensionName }} service
 [width="100%",cols="~,~,~,~",options="header"]
@@ -8,10 +34,12 @@
 | Description
 
 {{- range .Fields}}
-| {{- range $i, $value := .EnvVars }}{{- if $i }} +
+
+a| {{- range $i, $value := .EnvVars }}{{- if $i }} +
 {{ end -}}
 `{{- $value }}`
-{{- end }}
+{{- end }} +
+{{ .DeprecationLink }}
 a| [subs=-attributes]
 ++{{.Type}} ++
 a| [subs=-attributes]
@@ -22,4 +50,3 @@ a| [subs=-attributes]
 {{- end }}
 |===
 
-Since Version: `+` added, `-` deprecated