mirror/opencloud
1
0
Fork 0
mirror of https://github.com/opencloud-eu/opencloud.git synced 2026-02-28 09:29:41 -06:00
Code Issues Packages Projects Releases Wiki Activity

[docs-only] Improve dev docs

Browse Source
This commit is contained in:
mmattel
2024-08-22 19:19:55 +02:00
parent 233d108dbe
commit 54c304d3fc
15 changed files with 106 additions and 54 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/ocis/development/beta-testplan.md
View File

@@ -1,7 +1,7 @@
---
title: "Beta testplan"
date: 2022-03-24T00:00:00+00:00
weight: 37
weight: 20
geekdocRepo: https://github.com/owncloud/ocis
geekdocEditPath: edit/master/docs/ocis/development
geekdocFilePath: beta-testplan.md

2
docs/ocis/development/build-docs.md
View File

@@ -1,7 +1,7 @@
---
title: "Documentation"
date: 2020-07-27T08:39:38+00:00
weight: 99
weight: 20
geekdocRepo: https://github.com/owncloud/ocis
geekdocEditPath: edit/master/docs/ocis/development
geekdocFilePath: build-docs.md

2
docs/ocis/development/build.md
View File

@@ -1,7 +1,7 @@
---
title: "Build"
date: 2020-02-27T20:35:00+01:00
weight: 30
weight: 20
geekdocRepo: https://github.com/owncloud/ocis
geekdocEditPath: edit/master/docs/ocis/development
geekdocFilePath: build.md

2
docs/ocis/development/continuous-integration.md
View File

@@ -1,7 +1,7 @@
---
title: "Continuous Integration"
date: 2020-10-01T20:35:00+01:00
weight: 100
weight: 20
geekdocRepo: https://github.com/owncloud/ocis
geekdocEditPath: edit/master/docs/ocis/development
geekdocFilePath: continuous-integration.md

2
docs/ocis/development/debugging.md
View File

@@ -1,7 +1,7 @@
---
title: "Debugging"
date: 2020-03-19T08:21:00+01:00
weight: 50
weight: 20
geekdocRepo: https://github.com/owncloud/ocis
geekdocEditPath: edit/master/docs/ocis/development
geekdocFilePath: debugging.md

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

@@ -1,36 +0,0 @@
---
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
// 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"`
...
}
```
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. 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?
Once a variable has been finally removed, the annotations must be removed again from the code, since they do not serve any purpose from this point.

13
docs/ocis/development/envvars.md Normal file
View File

@@ -0,0 +1,13 @@
---
title: "Environment Variables"
date: 2024-08-22T15:41:00+01:00
weight: 20
geekdocRepo: https://github.com/owncloud/ocis
geekdocEditPath: edit/master/docs/ocis/development
geekdocFilePath: envvars.md
---
Environment variables are an essential part configuring services.
If you are going to create new ones or deprecate existing ones, mandatory read the [Envvar Naming Scope]({{< ref "services/general-info/envvar-scopes.md" >}}) and the
[Deprecating Variables]({{< ref "services/general-info/deprecating-variables.md" >}}) documentation for more details first before doing so.

2
docs/ocis/development/profiling.md
View File

@@ -1,7 +1,7 @@
---
title: "Profiling"
date: 2021-08-24T12:32:20+01:00
weight: 56
weight: 20
geekdocRepo: https://github.com/owncloud/ocis
geekdocEditPath: edit/master/docs/ocis/development
geekdocFilePath: profiling.md

2
docs/ocis/development/testing.md
View File

@@ -1,7 +1,7 @@
---
title: "Acceptance Testing"
date: 2018-05-02T00:00:00+00:00
weight: 38
weight: 20
geekdocRepo: https://github.com/owncloud/ocis
geekdocEditPath: edit/master/docs/ocis/development
geekdocFilePath: testing.md

2
docs/ocis/development/unit-testing/_index.md
View File

@@ -1,7 +1,7 @@
---
title: "Unit Testing"
date: 2024-04-25T00:00:00+00:00
weight: 5
weight: 20
geekdocRepo: https://github.com/owncloud/ocis
geekdocEditPath: edit/master/docs/ocis/development/unit-testing
geekdocFilePath: _index.md

2
docs/ocis/development/unit-testing/testing-pkg.md
View File

@@ -1,7 +1,7 @@
---
title: "Standard Library Testing"
date: 2024-04-25T00:00:00+00:00
weight: 15
weight: 10
geekdocRepo: https://github.com/owncloud/ocis
geekdocEditPath: edit/master/docs/ocis/development/unit-testing
geekdocFilePath: testing-pkg.md

54
docs/services/general-info/deprecating-variables.md Normal file
View File

@@ -0,0 +1,54 @@
---
title: "Envvar Deprecation"
date: 2024-08-22T15:41:00+01:00
weight: 20
geekdocRepo: https://github.com/owncloud/ocis
geekdocEditPath: edit/master/docs/services/general-info
geekdocFilePath: deprecating-variables.md
---
{{< toc >}}
## Deprecating Environment Variables
Sometimes it is necessary to deprecate an environment variable to align the naming with conventions or remove it at all. We therefore added annotations to automate the *documentation* process.
The relevant annotations in the envvar struct tag are:
* `deprecationVersion`\
The release an envvar is announced for deprecation.
* `removalVersion`\
The version it is finally going to be removed is defined via the mandatory placeholder `%%NEXT_PRODUCTION_VERSION%%`, not an actual version number.
* `deprecationInfo`\
The reason why it got deprecated.
* `deprecationReplacement`\
Only if it is going to be replaced, not necessary if removed.
{{< hint warning >}}
During the development cycle, the value for the `removalVersion` must be set to `%%NEXT_PRODUCTION_VERSION%%`. This placeholder will be removed by the real version number during the production releasing process.
{{< /hint >}}
For the documentation only to show the correct value for the `removalVersion`, our docs helper scripts will automatically generate the correct version to be printed in the documentation. If `%%NEXT_PRODUCTION_VERSION%%` is found in the query, it will be replaced with `next-prod`, else the value found is used.
### Example
```golang
// 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:"%%NEXT_PRODUCTION_VERSION%%" deprecationInfo:"REVA_GATEWAY changing name for consistency" deprecationReplacement:"OCIS_REVA_GATEWAY"`
...
}
```
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. 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 | `%%NEXT_PRODUCTION_VERSION%%` |
| 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?
Once a variable has been finally been removed, the annotations must be removed again from the code, since they don't serve any purpose.

34
docs/services/general-info/envvar-scopes.md
View File

@@ -1,5 +1,5 @@
---
title: Envvar Naming Scope
title: Envvar Naming Scopes
date: 2023-03-23T00:00:00+00:00
weight: 20
geekdocRepo: https://github.com/owncloud/ocis
@@ -8,6 +8,8 @@ geekdocFilePath: envvar-scopes.md
geekdocCollapseSection: true
---
{{< toc >}}
The scope of an environment variable can be derived from its name. Therefore, it is important to follow the correct naming scheme to enable easy and proper identification. This is important when either:
- a new local envvar is introduced.
@@ -20,7 +22,7 @@ The scope of an environment variable can be derived from its name. Therefore, it
- Mandatory when used in a service, a global envvar must have a local counterpart.
- Variables that do not belong to any service are by definition global.
## Name Scope
## Naming Scope
### Local Envvars
@@ -34,14 +36,32 @@ Note that this envvar is the global representation of the local example from abo
To get a list of global envvars used in all services, see the [Global Environment Variables](https://doc.owncloud.com/ocis/next/deployment/services/env-vars-special-scope.html#global-environment-variables) table in the ocis admin documentation.
### Lifecycle
## Lifecycle of Envvars
In the struct tag values of our config data types, we are using three key/value pairs to document the lifecycle of a config variable: `introductionVersion`, `deprecationVersion` and `removalVersion`. During the development cycle, a new value should set to `%%NEXT%%` as long as no release is scheduled. During the release process, the placeholder will be replaced with the actual version number. Our docs helper scripts will then automatically generate the correct documentation based on the version number.
The envvar struct tag contains at maximum the following key/value pairs to document the lifecycle of a config variable:
## Deprecations
* `introductionVersion`
* `deprecationVersion`
* `removalVersion`
* `deprecationInfo`
* `deprecationReplacement`
All environment variable types that are used in a service follow the same [deprecation rules]({{< ref "ocis/development/deprecating-variables/_index.md" >}}) independent of their scope.
### Introduce new Envvars
## Separating Envvars
If a new envvar is introduced, only the `introductionVersion` is required.
{{< hint warning >}}
During the development cycle, the value for the `introductionVersion` must be set to `%%NEXT%%`. This placeholder will be removed by the real version number during the production releasing process.
{{< /hint >}}
For the documentation only to show the correct value for the `IV` (introduction version), our docs helper scripts will automatically generate the correct version to be printed in the documentation. If `%%NEXT%%` is found in the query, it will be replaced with `next`, else the value found is used.
During the releasing process for a production release, the placeholder `%%NEXT%%` has to be replaced with the new production version number like `%%NEXT%%` → `7.0.0`.
### Deprecate Existing Envvars
See the [deprecation rules]({{< ref "./deprecating-variables.md" >}}) documentation fo rmore details.
## Separating Multiple Envvars
When multiple envvars are defined for one purpose like a global and local one, use `;` (semicolon) to properly separate the envvars in go code. Though it is possible to separate with `,` (comma) according go rules, the current implementation of the docs generation process only recognizes semicolons as separator.

3
docs/services/general-info/new-service-checklist.md
View File

@@ -32,7 +32,7 @@ Use this checklist with copy/paste in your PR - right from the beginning. It ren
- Add the service config to `ocis-pkg/config/defaultconfig.go`
- [ ] If the service is using service accounts, add it to `ocis/pkg/init/init.go`
- [ ] Add the service to `.drone.star` to enable CI.
- [ ] Inform doc team in an _early stage_ to review the readme AND the environment variables created.
- [ ] Inform doc team in an *early stage* to review the readme AND the environment variables created.
- The description must reflect the behaviour AND usually has a positive code quality impact.
- [ ] Create proper description strings for envvars - see other services for examples, especially when it comes to multiple values. This must include:
- base description, set of available values, description of each value.
@@ -44,4 +44,5 @@ Use this checklist with copy/paste in your PR - right from the beginning. It ren
- [ ] Make sure to have a function `FullDefaultConfig()` in `pkg/config/defaults/defaultconfig.go` of your service. It is needed to create the documentation.
- [ ] Add metrics to the code to enable monitoring. See the proxy service for implementation details.
- Plus add documentation about monitoring in the README.md file
- [ ] When the service requires translations that have to be covered by the service and are not sourced by web, see the [add translation]({{< ref "./add-translations.md" >}}) documentation for more details.
```