eliott/ocis
1
0
Fork 0
mirror of https://github.com/owncloud/ocis synced 2026-04-25 17:25:21 +02:00
Code Issues Packages Projects Releases Wiki Activity

[docs-only] Update check-env-var-annotoation.sh script

Browse Source 
Signed-off-by: Martin Mattel <github@diemattels.at>
This commit is contained in:
Martin Mattel
2026-04-01 12:07:02 +02:00
parent f8cf3429de
commit 42a7c5f334
3 changed files with 71 additions and 41 deletions
Download Patch File Download Diff File Expand all files Collapse all files

62
.make/check-env-var-annotations.sh
View File

@@ -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"

23
docs/services/general-info/envvars/envvar-naming-scopes.md
View File

@@ -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

27
docs/services/general-info/envvars/new-release-process.md
View File

@@ -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