From c054f16c289825d08cad0c1684d6338368fb361c Mon Sep 17 00:00:00 2001
From: mmattel <github@diemattels.at>
Date: Wed, 12 Apr 2023 16:58:08 +0200
Subject: [PATCH] [docs-only] Create a General Info page plus content in
 services for owncloud.dev

---
 docs/services/general-info/_index.md          | 18 +++++++++
 docs/services/general-info/envvar-scopes.md   | 39 +++++++++++++++++++
 .../new-service-checklist.md                  |  5 ++-
 .../{ => general-info}/port-ranges.md         |  4 +-
 4 files changed, 62 insertions(+), 4 deletions(-)
 create mode 100644 docs/services/general-info/_index.md
 create mode 100644 docs/services/general-info/envvar-scopes.md
 rename docs/services/{ => general-info}/new-service-checklist.md (95%)
 rename docs/services/{ => general-info}/port-ranges.md (99%)

diff --git a/docs/services/general-info/_index.md b/docs/services/general-info/_index.md
new file mode 100644
index 000000000..2c4169e00
--- /dev/null
+++ b/docs/services/general-info/_index.md
@@ -0,0 +1,18 @@
+---
+title: Rclone
+date: 2021-11-17T00:00:00+00:00
+weight: 0
+geekdocRepo: https://github.com/owncloud/ocis
+geekdocEditPath: edit/master/docs/services/general-info
+geekdocFilePath: _index.md
+geekdocCollapseSection: true
+---
+
+## General Information
+
+This section provides general information valid for all services.
+
+## Table of Contents
+
+{{< toc-tree >}}
+
diff --git a/docs/services/general-info/envvar-scopes.md b/docs/services/general-info/envvar-scopes.md
new file mode 100644
index 000000000..3aed213f3
--- /dev/null
+++ b/docs/services/general-info/envvar-scopes.md
@@ -0,0 +1,39 @@
+---
+title: Environment Variable Naming Scope
+date: 2023-03-23T00:00:00+00:00
+weight: 10
+geekdocRepo: https://github.com/owncloud/ocis
+geekdocEditPath: edit/master/docs/services/general-info
+geekdocFilePath: envvar-scopes.md
+geekdocCollapseSection: true
+---
+
+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.
+-   a new global envvar is added to an existing local envvar.
+
+## Envvar Definition
+
+-   A variable that is only used in a particular service is a **local envvar**.
+-   A variable that is used in more than one service is a **global envvar**.
+-   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
+
+### Local Envvars
+
+A local envvar always starts with the the service name like `POSTPROCESSING_LOG_FILE`.
+
+### Global Envvars
+
+A global envvar always starts with `OCIS_` like `OCIS_LOG_FILE`.
+
+Note that this envvar is the global version of the local example above.
+
+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.
+
+## Deprecations
+
+All environment variable types that are used in a service follow the same deprecation rules independent of their scope.
diff --git a/docs/services/new-service-checklist.md b/docs/services/general-info/new-service-checklist.md
similarity index 95%
rename from docs/services/new-service-checklist.md
rename to docs/services/general-info/new-service-checklist.md
index d5a99ee64..da7eb3f1e 100644
--- a/docs/services/new-service-checklist.md
+++ b/docs/services/general-info/new-service-checklist.md
@@ -1,9 +1,9 @@
 ---
 title: New Service Checklist
 date: 2023-03-23T00:00:00+00:00
-weight: 0
+weight: 10
 geekdocRepo: https://github.com/owncloud/ocis
-geekdocEditPath: edit/master/docs/services
+geekdocEditPath: edit/master/docs/services/general-info
 geekdocFilePath: new-service-checklist.md
 geekdocCollapseSection: true
 ---
@@ -23,6 +23,7 @@ Use this checklist with copy/paste in your PR - right from the beginning. It ren
     bad `<img src="https://github.com/owncloud/ocis/blob/master/services/graph/images/mermaid-graph.svg" width="500" />`  
     good `<img src="https://raw.githubusercontent.com/owncloud/ocis/master/services/graph/images/mermaid-graph.svg" width="500" />`
 - [ ] If new CLI command are introduced, that command must be described in readme.md.
+- [ ] If new global envvar is introduced, the name must start with `OCIS_`.
 - [ ] Add the service to the makefile in the ocis repo root.
 - [ ] Make the service startable for binary and individual startup:
   - For single binary add service to `ocis/pkg/runtime`
diff --git a/docs/services/port-ranges.md b/docs/services/general-info/port-ranges.md
similarity index 99%
rename from docs/services/port-ranges.md
rename to docs/services/general-info/port-ranges.md
index 7952337b3..38d2d3f82 100644
--- a/docs/services/port-ranges.md
+++ b/docs/services/general-info/port-ranges.md
@@ -1,9 +1,9 @@
 ---
 title: Port Ranges
 date: 2018-05-02T00:00:00+00:00
-weight: 0
+weight: 10
 geekdocRepo: https://github.com/owncloud/ocis
-geekdocEditPath: edit/master/docs/services
+geekdocEditPath: edit/master/docs/services/general-info
 geekdocFilePath: port-ranges.md
 geekdocCollapseSection: true
 ---