owncloud · mmattel · Apr 7, 2026 · Apr 1, 2026
diff --git a/.make/check-env-var-annotations.sh b/.make/check-env-var-annotations.sh
@@ -1,7 +1,7 @@
 #!/bin/bash
 
-# The following grep will filter out every line containing an `env` annotation.
-# It will ignore every line that already has a valid `introductionVersion` annotation.
+# the following grep will filter out every line containing an `env` annotation
+# and prints all entries found that are invalid. this is required to see where CI might fail
 
 RED=$(echo -e "\033[0;31m")
 GREEN=$(echo -e "\033[0;32m")
@@ -14,48 +14,64 @@ print_introduction_version_examples() {
 		  ${GREEN}Valid examples:${NORM}
 
 		  introductionVersion:"pre5.0"
-		  introductionVersion:"5.0"
+		  introductionVersion:"5.0" deprecationVersion:"7.0.0"
 		  introductionVersion:"4.9.3-rc5"
-		  introductionVersion:"5.0.1-cheesecake"
 		  introductionVersion:"5.10.100.15"
 		  introductionVersion:"0.0"
-		  introductionVersion:"releaseX"  # acceptable alphabetical version
-		  introductionVersion:"Addams"    # another alphabetical example such as a release name
+		  introductionVersion:"release" deprecationVersion:"7.0.0"
+		  introductionVersion:"releaseX" deprecationVersion:"7.0.0"
+		  introductionVersion:"Addams" deprecationVersion:"7.0.0"
 
 		  ${RED}Invalid examples:${NORM}
 
-		  introductionVersion:"5.0cheesecake"
-		  introductionVersion:"5"
-		  introductionVersion:"5blueberry"
+		  introductionVersion:""
+		  introductionVersion:"  "
+		  introductionVersion:"-"
+		  introductionVersion:"--"
+		  introductionVersion:"51.0cheesecake" deprecationVersion:"7.0.0"
+		  introductionVersion:"50..0.1-cheesecake"
+		  introductionVersion:"15"
+		  introductionVersion:"54blueberry"
 		  introductionVersion:"5-lasagna"
-		  introductionVersion:"4.9.3rc5"
+		  introductionVersion:"5.lasagna-rc1"
+		  introductionVersion:"4.9.3rc-5" deprecationVersion:"7.0.0"
+		  introductionVersion:"5B-rc1" deprecationVersion:"7.0.0"
 
-		  See the dev docs for more details: https://owncloud.dev/services/general-info/envvars/envvar-naming-scopes/
+		  See the envvar life cycle in the dev docs for more details:
+		  https://owncloud.dev/services/general-info/envvars/envvar-naming-scopes/
 	EOL
 }
 
 ERROR=0
 
-SEMVER_REGEX="([0-9]|[1-9][0-9]*)(\.([0-9]|[1-9][0-9]*)){1,2}(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+)?"
-ALPHA_REGEX="[A-Za-z]+[A-Za-z0-9-]*"
+# note that our semver is not fully compliant because we do not have a patch version for new envvars
+# if you want to test, use the examples above and take the blocks separated by `|` (or)
+SEMVER_REGEX='(?:introductionVersion:\")(?:(?:[^\dA-Za-z]*?)\"|(?:\d+[A-z]+).*?\"|(?:\d*?\")|(?:\d*?[-\.]+\D.*?\")|(?:\d*?[\.]{2,}.*?\")|(?:\d+\.\d+[A-z]+\")|(?:(?:\d+\.)+\d+[A-z]+.*?\"))'
 
-QI=$(git grep -n "env:" -- '*.go' |grep -v -P "introductionVersion:\"($SEMVER_REGEX|(pre5\\.0)|($ALPHA_REGEX))\""|grep -v "_test.go"|grep -v "vendor/")
+# filter out the the following paths
+EXCLUDE_PATHS='_test.go|vendor/'
+
+# query the code
+QI=$(git grep -n "env:" -- '*.go' | grep -v -E "${EXCLUDE_PATHS}" | grep --color=always -P "${SEMVER_REGEX}")
+
+# count the results found
+RESULTS_INTRO=$(echo "${QI}"|wc -l)
 
 # add a new line after each hit, eol identified via "´ which only appears at the end of each envvar string definition
 QUERY_INTRO=$(echo "${QI}" | sed "s#\"\`#\"\`\n#g")
 
-RESULTS_INTRO=$(echo "${QUERY_INTRO}"|wc -l)
-
 echo "Checking introductionVersion annotations"
 
 if [ "${QUERY_INTRO}" != "" ] && [ "${RESULTS_INTRO}" -gt 0 ]; then
   echo
   echo "==============================================================================================="
-  echo ${RED}"The following ${RESULTS_INTRO} items contain invalid or missing introductionVersion annotation(s):"${NORM}
+  echo ${RED}"The following item(s) contain invalid or missing introductionVersion annotation(s):"${NORM}
   echo "==============================================================================================="
   echo
   echo "$QUERY_INTRO"
   echo
+  echo ${GREEN}"${RESULTS_INTRO} items found"${NORM}
+  echo
   print_introduction_version_examples
   echo
   ERROR=1
@@ -64,21 +80,25 @@ else
   echo
 fi
 
-# The following grep will filter out every line containing an `env` annotation
-# it will ignore every line that has allready a valid `desc` annotation
+# the following grep will filter out every line containing an `env` annotation and
+# will print each line that has an invalid `desc` annotation.
 
-QUERY_DESC=$(git grep -n "env:" -- '*.go' |grep -v -P "desc:\".{10,}\""|grep -v "_test.go"|grep -v "vendor/")
+# query the code
+QUERY_DESC=$(git grep -n "env:" -- '*.go' | grep -v -E "${EXCLUDE_PATHS}" | grep -v --color=always  -P "desc:\".{10,}\"")
 
+# count the results found
 RESULTS_DESC=$(echo "${QUERY_DESC}"|wc -l)
 
 echo "Checking description annotations"
 
 if [ "${QUERY_DESC}" != "" ] && [ "${RESULTS_DESC}" -gt 0 ]; then
   echo
   echo "==============================================================================================="
-  echo ${RED}"The following ${RESULTS_DESC} items contain invalid or missing description annotation:"${NORM}
+  echo ${RED}"The following item(s) contain invalid or missing description annotation:"${NORM}
   echo "==============================================================================================="
   echo "$QUERY_DESC"
+  echo
+  echo ${GREEN}"${RESULTS_DESC} items found"${NORM}
   ERROR=1
 else
   echo "All description annotations are valid"

diff --git a/docs/services/general-info/envvars/envvar-naming-scopes.md b/docs/services/general-info/envvars/envvar-naming-scopes.md
@@ -52,24 +52,25 @@ The envvar struct tag contains at maximum the following key/value pairs to docum
 
 ### Introduce new Envvars
 
-If a new envvar is introduced, the complete struct needs to be added, but only the `introductionVersion` requires data.
+* If a **new** envvar is introduced, the entire structure must be added, including the `introductionVersion` field. Note that 'introduced' means, that the new envvar was not present in any of the services.
 
-{{< hint info >}}
-* During development, set `introductionVersion` to a short, **alphabetic code name** that represents the upcoming release (e.g. `releaseX`).
-* This identifier stays constant until the release receives its final production semantic-version number.
-{{< /hint >}}
+  {{< hint info >}}
+  * During development, set the `introductionVersion` to a short, **alphabetic code name** that represents the upcoming release such as `releaseX` or the project name for that release such as `Daledda`.
+  * This identifier stays constant until the release receives its final production semantic-version number.
+  * Although the pipeline checks the semver string when a PR is created, you can perform this check upfront manually by entering the following command from the ocis root:
 
-The docs helper scripts render these alphabetic identifiers verbatim. They appear in the next (master) branch of the admin docs as rendered here.
+    ```bash
+    .make/check-env-var-annotations.sh
+    ```
+  {{< /hint >}}
 
-Once the release is cut, before tagging, replace them with the actual semantic version (e.g. `releaseX` → `7.2.0`). 
+  The doc helper scripts render these alphabetic identifiers verbatim. They appear in the next (master) branch of the admin documentation exactly as they are entered.
 
-{{< hint info >}}
-A new production version **MUST NOT** contain any alphabetic identifyers but the semantic version only.
-{{< /hint >}}
+* See the [Set the Correct IntroductionVersion]({{< ref "./new-release-process/" >}}) documentation before starting a new release candidate.
 
 ### Adding Envvars to Existing Ones
 
-If an envvar has been introduced with a particular version, the `introductionVersion` gets a value accordingly. If an additional envvar like a global one is added to this existing envvar later on, the introduction version will *not* be changed.
+If an envvar has been introduced with a particular release, the `introductionVersion` got a semver value accordingly. If an additional envvar is added to this existing one such as a global envvar, the introduction version **must not** be changed.
 
 ### Deprecate Existing Envvars
 

diff --git a/docs/services/general-info/envvars/new-release-process.md b/docs/services/general-info/envvars/new-release-process.md
@@ -23,13 +23,26 @@ Ask the developers if envvars of this type have been changed (added or removed).
 * From the ocis root run:\
 `sudo make docs-clean`\
 `make docs-generate`\
-Drop any changes in `env_vars.yaml`!
+Discard any changes in `env_vars.yaml`!
 * Check if there is a change in the `extended-envars.yaml` output.\
-If so, process [Extended Envvars - Fixing Changed Item]({{< ref "./special-envvars.md#fixing-changed-items" >}}).
+If so, process [Extended Envvars - Fixing Changed Items]({{< ref "./special-envvars.md#fixing-changed-items" >}}).
 * When done, re-run `make docs-generate` and check if the output matches the expectations in `./docs/services/_includes/adoc/extended_configvars.adoc`.
 
 ## Ordinary Envvars
 
+### Set the Correct IntroductionVersion
+
+* Once the release is cut, **before** creating the first release candidate, replace them with the actual semantic version (e.g. `releaseX` → `8.1.0`). To find these placeholders in `introductionVersion` keys, you can run a helper script by issuing the following command:
+  ```bash
+  docs/ocis/helpers/identify_envvar_placeholder_names.sh
+  ```
+
+  {{< hint info >}}
+  A new production version **MUST NOT** contain any alphabetic identifyers but the semantic version only, using **major, minor and a patch version, which is always 0!**.
+  {{< /hint >}}
+
+* Create a PR and merge it **before** taking the next step maintaining the `env_vars.yaml` file! Do not forget to rebase your local git repo.
+
 ### Maintain the 'env_vars.yaml' File
 
 This is **mandatory for a new release** !
@@ -38,17 +51,13 @@ This is **mandatory for a new release** !
 `sudo make docs-clean`\
 `make docs-generate`\
 Any changes in `env_vars.yaml` are now considered.
-* This file will most likely show changes and merging them is **essential** as base for **added/removed or deprecated envvars**. Note that this file will get additions/updates only, but items never get deleted automatically !!\
+* This file will most likely show changes and merging them is **essential** as base for **added/removed or deprecated envvars** (envvar deltas). Note that this file will get additions/updates only, but items never get deleted automatically !!\
 {{< hint info >}}
 Note that due to how the code is currently designed, **things may get shifted** around though no real changes have been introduced.
 {{< /hint >}}
-* First, check if any **alphabetic code names** are present in the changes. See [Introduce new Envvars]({{< ref "./envvar-naming-scopes.md/#introduce-new-envvars" >}}).
-  * If so, create a new branch and replace them in the **service containing the source** with the actual semantic version (e.g. `releaseX` → `7.2.0`) first. Note that ALL of major, minor and patch numbers must be present, including patch versions == `0`.
-  * If all changes are applied, rerun `make docs-generate` and check if all changes are incorporated in the yaml file.
-  * Create a PR and merge these changes, dont forget to do a local pull of master afterwards...
-* With a new branch, remove all envvars from the `env_vars.yaml` file manually that have formerly been deprecated and removed from the code.
+* With a new branch, remove all envvars from the `env_vars.yaml` file manually that have formerly been deprecated **and removed** from the code.
 * Commit the changes and merge it.\
-Now `env_vars.yaml` is up to date on the repo in master, next steps are based on this state!
+Now, `env_vars.yaml` is up to date in the repo in master. Next steps depend on this updated file!
 
 ### Create Envvar Delta Files