From 42a7c5f334a1e12cb3c3c9711734f03757a37dba Mon Sep 17 00:00:00 2001 From: Martin Mattel Date: Wed, 1 Apr 2026 12:07:02 +0200 Subject: [PATCH] [docs-only] Update check-env-var-annotoation.sh script Signed-off-by: Martin Mattel --- .make/check-env-var-annotations.sh | 62 ++++++++++++------- .../envvars/envvar-naming-scopes.md | 23 +++---- .../envvars/new-release-process.md | 27 +++++--- 3 files changed, 71 insertions(+), 41 deletions(-) diff --git a/.make/check-env-var-annotations.sh b/.make/check-env-var-annotations.sh index a3fa057561c..10f46aac80f 100755 --- 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,11 +80,13 @@ 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" @@ -76,9 +94,11 @@ 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 index 5442808910e..ca9df8e829d 100644 --- 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 index 0afc323e1de..db9f1636faf 100644 --- 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