mirror/opencloud
1
0
Fork 0
mirror of https://github.com/opencloud-eu/opencloud.git synced 2026-01-25 14:08:53 -06:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #7131 from owncloud/mmattel-patch-1

Browse Source 
[docs-only] Update deprecating-variables.md
This commit is contained in:
Martin
2023-08-28 08:56:26 +02:00
committed by GitHub
parent a5ac3e7ce7 2892c603aa
commit 7b09d1cdb8
1 changed files with 8 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files

19
docs/ocis/development/deprecating-variables.md
View File

@@ -10,17 +10,14 @@ geekdocFilePath: deprecating-variables.md
## 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.
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"`
// Notifications defines the config options for the notifications service.
type Notifications struct {
RevaGateway string `yaml:"reva_gateway" env:"OCIS_REVA_GATEWAY;REVA_GATEWAY" desc:"CS3 gateway used to look up user metadata" deprecationVersion:"3.0" removalVersion:"4.0.0" deprecationInfo:"REVA_GATEWAY changing name for consistency" deprecationReplacement:"OCIS_REVA_GATEWAY"`
...
}
```
@@ -29,10 +26,10 @@ There are four different annotation variables that need to be filled:
| Annotation |Description| Format|
|---|---|---|
| deprecationVersion| The version the variable will be deprecated| semver (e.g. 1.6.2)|
| removalVersion| The version the variable will be removed from the codebase. Note that according to semver, a removal can only be made in a major version change| semver (e.g. 4.0.0)|
| 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) |
| deprecationReplacement | The name of the variable that is going to replace the deprecated one.| string (e.g. NATS_HOST_ADDRESS)|
| deprecationVersion | The version the variable will be deprecated | semver (e.g. 3.0)|
| removalVersion| The version the variable will be removed from the codebase. Note that according to semver, a removal **MUST NOT** be made in a minor or patch version change, but only in a major release | semver (e.g. 4.0.0) |
| 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) |
| deprecationReplacement | The name of the variable that is going to replace the deprecated one.| string (e.g. NATS_HOST_ADDRESS) |
### What happens next?