From 28c6d1dbfa0a78bb71c3c8813a2c3cf53b8d2003 Mon Sep 17 00:00:00 2001 From: Christian Richter Date: Tue, 29 Nov 2022 15:55:14 +0100 Subject: [PATCH] Add dev-docs for variable descrption Signed-off-by: Christian Richter --- .../ocis/development/deprecating-variables.md | 35 +++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100644 docs/ocis/development/deprecating-variables.md diff --git a/docs/ocis/development/deprecating-variables.md b/docs/ocis/development/deprecating-variables.md new file mode 100644 index 0000000000..be7fd2f081 --- /dev/null +++ b/docs/ocis/development/deprecating-variables.md @@ -0,0 +1,35 @@ +--- +title: "Deprecating Variables" +date: 2022-11-29T15:41:00+01:00 +geekdocRepo: https://github.com/owncloud/ocis +geekdocEditPath: edit/master/docs/ocis/development +geekdocFilePath: deprecating-variables.md +--- + +{{< toc >}} + +## Deprecating Environment Variables + +Sometimes it is necessary to deprecate environment to align their naming with +conventions. We therefore added annotations to automate the documentation +process. It is necessary to know when the variable is going to be deprecated, +when it is going to be removed and why. + +### Example + +```golang +// Nats is the nats config +type Nats struct { +Host string `yaml:"host" env:"NATS_HOST_ADDRESS,NATS_NATS_HOST" desc:"Bind address." deprecationVersion:"1.6.2" removalVersion:"1.7.5" deprecationInfo:"NATS_NATS_HOST is confusing" deprecationReplacement:"NATS_HOST_ADDRESS"` +... +} +``` + +There are four different annotation variables that need to be filled: + +| Annotation |Description| Format| +|---|---|---| +| depreactionVersion| The version the variable will be deprecated| semver (e.g. 1.6.2)| +| removalVersion| The version the variable will be removed from the codebase| semver (e.g. 1.7.3)| +| deprecationInfo| Information why the variable is deprecated, must start with the name of the variable in order to avoid confusion, when there are multiple options in the `env:`-field | string (e.g. NATS_NATS_HOST is confusing) | +| depreactionReplacement | The name of the variable that is going to replace the deprecated on.| string (e.g. NATS_HOST_ADDRESS)|