From 54c304d3fcef1251a5e51a072c1fcbcb2fa9d88b Mon Sep 17 00:00:00 2001 From: mmattel Date: Thu, 22 Aug 2024 19:19:55 +0200 Subject: [PATCH 1/2] [docs-only] Improve dev docs --- docs/ocis/development/beta-testplan.md | 2 +- docs/ocis/development/build-docs.md | 2 +- docs/ocis/development/build.md | 2 +- .../development/continuous-integration.md | 2 +- docs/ocis/development/debugging.md | 2 +- .../ocis/development/deprecating-variables.md | 36 ------------- docs/ocis/development/envvars.md | 13 +++++ docs/ocis/development/profiling.md | 2 +- docs/ocis/development/testing.md | 2 +- docs/ocis/development/unit-testing/_index.md | 2 +- .../development/unit-testing/testing-pkg.md | 2 +- .../general-info/deprecating-variables.md | 54 +++++++++++++++++++ docs/services/general-info/envvar-scopes.md | 34 +++++++++--- .../general-info/new-service-checklist.md | 3 +- services/activitylog/README.md | 2 +- 15 files changed, 106 insertions(+), 54 deletions(-) delete mode 100644 docs/ocis/development/deprecating-variables.md create mode 100644 docs/ocis/development/envvars.md create mode 100644 docs/services/general-info/deprecating-variables.md diff --git a/docs/ocis/development/beta-testplan.md b/docs/ocis/development/beta-testplan.md index 51fa37368d..b66e908404 100644 --- a/docs/ocis/development/beta-testplan.md +++ b/docs/ocis/development/beta-testplan.md @@ -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 diff --git a/docs/ocis/development/build-docs.md b/docs/ocis/development/build-docs.md index dc1196f66c..44624b234c 100644 --- a/docs/ocis/development/build-docs.md +++ b/docs/ocis/development/build-docs.md @@ -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 diff --git a/docs/ocis/development/build.md b/docs/ocis/development/build.md index d7c1914581..e78409335f 100644 --- a/docs/ocis/development/build.md +++ b/docs/ocis/development/build.md @@ -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 diff --git a/docs/ocis/development/continuous-integration.md b/docs/ocis/development/continuous-integration.md index 3c9774f656..b5907d7cdc 100644 --- a/docs/ocis/development/continuous-integration.md +++ b/docs/ocis/development/continuous-integration.md @@ -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 diff --git a/docs/ocis/development/debugging.md b/docs/ocis/development/debugging.md index a9721fb9ff..5d0df756d4 100644 --- a/docs/ocis/development/debugging.md +++ b/docs/ocis/development/debugging.md @@ -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 diff --git a/docs/ocis/development/deprecating-variables.md b/docs/ocis/development/deprecating-variables.md deleted file mode 100644 index e69aa742fc..0000000000 --- a/docs/ocis/development/deprecating-variables.md +++ /dev/null @@ -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. diff --git a/docs/ocis/development/envvars.md b/docs/ocis/development/envvars.md new file mode 100644 index 0000000000..4e7e317438 --- /dev/null +++ b/docs/ocis/development/envvars.md @@ -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. diff --git a/docs/ocis/development/profiling.md b/docs/ocis/development/profiling.md index 9afb747cda..47a19431c9 100644 --- a/docs/ocis/development/profiling.md +++ b/docs/ocis/development/profiling.md @@ -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 diff --git a/docs/ocis/development/testing.md b/docs/ocis/development/testing.md index fe14492bd8..1dac8f3be2 100644 --- a/docs/ocis/development/testing.md +++ b/docs/ocis/development/testing.md @@ -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 diff --git a/docs/ocis/development/unit-testing/_index.md b/docs/ocis/development/unit-testing/_index.md index 952819d3e4..48d7215b50 100644 --- a/docs/ocis/development/unit-testing/_index.md +++ b/docs/ocis/development/unit-testing/_index.md @@ -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 diff --git a/docs/ocis/development/unit-testing/testing-pkg.md b/docs/ocis/development/unit-testing/testing-pkg.md index 8c5161005c..81ce85905e 100644 --- a/docs/ocis/development/unit-testing/testing-pkg.md +++ b/docs/ocis/development/unit-testing/testing-pkg.md @@ -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 diff --git a/docs/services/general-info/deprecating-variables.md b/docs/services/general-info/deprecating-variables.md new file mode 100644 index 0000000000..eff2f312f4 --- /dev/null +++ b/docs/services/general-info/deprecating-variables.md @@ -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. diff --git a/docs/services/general-info/envvar-scopes.md b/docs/services/general-info/envvar-scopes.md index ffe7f1acb0..3c9068867e 100644 --- a/docs/services/general-info/envvar-scopes.md +++ b/docs/services/general-info/envvar-scopes.md @@ -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. diff --git a/docs/services/general-info/new-service-checklist.md b/docs/services/general-info/new-service-checklist.md index 613985cfae..2640ca8c14 100644 --- a/docs/services/general-info/new-service-checklist.md +++ b/docs/services/general-info/new-service-checklist.md @@ -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. ``` diff --git a/services/activitylog/README.md b/services/activitylog/README.md index b7238194a8..8918b3e995 100644 --- a/services/activitylog/README.md +++ b/services/activitylog/README.md @@ -1,4 +1,4 @@ -# Activitylog Service +# Activitylog The `activitylog` service is responsible for storing events (activities) per resource. From e679c01dfcdd70d392ed5f91c57677400f2e5447 Mon Sep 17 00:00:00 2001 From: Martin Date: Fri, 23 Aug 2024 08:44:46 +0200 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: Phil Davis --- docs/ocis/development/envvars.md | 4 ++-- docs/services/general-info/deprecating-variables.md | 8 ++++---- docs/services/general-info/envvar-scopes.md | 4 ++-- 3 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/ocis/development/envvars.md b/docs/ocis/development/envvars.md index 4e7e317438..c401b370d8 100644 --- a/docs/ocis/development/envvars.md +++ b/docs/ocis/development/envvars.md @@ -7,7 +7,7 @@ geekdocEditPath: edit/master/docs/ocis/development geekdocFilePath: envvars.md --- -Environment variables are an essential part configuring services. +Environment variables are an essential part of 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 +If you are going to create new ones or deprecate existing ones, you must 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. diff --git a/docs/services/general-info/deprecating-variables.md b/docs/services/general-info/deprecating-variables.md index eff2f312f4..bc77eebe9f 100644 --- a/docs/services/general-info/deprecating-variables.md +++ b/docs/services/general-info/deprecating-variables.md @@ -11,7 +11,7 @@ geekdocFilePath: deprecating-variables.md ## 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. +Sometimes it is necessary to deprecate an environment variable to align the naming with conventions or remove it completely. We therefore added annotations to automate the *documentation* process. The relevant annotations in the envvar struct tag are: @@ -20,15 +20,15 @@ The relevant annotations in the envvar struct tag are: * `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. + The reason why it was 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. +During the development cycle, the value for the `removalVersion` must be set to `%%NEXT_PRODUCTION_VERSION%%`. This placeholder will be replaced 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. +For the documentation 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 diff --git a/docs/services/general-info/envvar-scopes.md b/docs/services/general-info/envvar-scopes.md index 3c9068867e..f043cf36d9 100644 --- a/docs/services/general-info/envvar-scopes.md +++ b/docs/services/general-info/envvar-scopes.md @@ -54,13 +54,13 @@ If a new envvar is introduced, only the `introductionVersion` is required. 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. +For the documentation 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. +See the [deprecation rules]({{< ref "./deprecating-variables.md" >}}) documentation for more details. ## Separating Multiple Envvars