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

Merge pull request #12176 from owncloud/update_check_envvar_version_annotion

Browse Source 
[docs-only] Update check-env-var-annotoation.sh script
This commit is contained in:
Martin
2026-04-07 16:26:43 +02:00
committed by GitHub
parent f8cf3429de 42a7c5f334
commit 5ea1da9aba
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 #!/bin/bash
# The following grep will filter out every line containing an `env` annotation. # the following grep will filter out every line containing an `env` annotation
# It will ignore every line that already has a valid `introductionVersion` annotation. # and prints all entries found that are invalid. this is required to see where CI might fail
RED=$(echo -e "\033[0;31m") RED=$(echo -e "\033[0;31m")
GREEN=$(echo -e "\033[0;32m") GREEN=$(echo -e "\033[0;32m")
@@ -14,48 +14,64 @@ print_introduction_version_examples() {
${GREEN}Valid examples:${NORM} ${GREEN}Valid examples:${NORM}
introductionVersion:"pre5.0" introductionVersion:"pre5.0"
introductionVersion:"5.0" introductionVersion:"5.0" deprecationVersion:"7.0.0"
introductionVersion:"4.9.3-rc5" introductionVersion:"4.9.3-rc5"
introductionVersion:"5.0.1-cheesecake"
introductionVersion:"5.10.100.15" introductionVersion:"5.10.100.15"
introductionVersion:"0.0" introductionVersion:"0.0"
introductionVersion:"releaseX" # acceptable alphabetical version introductionVersion:"release" deprecationVersion:"7.0.0"
introductionVersion:"Addams" # another alphabetical example such as a release name introductionVersion:"releaseX" deprecationVersion:"7.0.0"
introductionVersion:"Addams" deprecationVersion:"7.0.0"
${RED}Invalid examples:${NORM} ${RED}Invalid examples:${NORM}
introductionVersion:"5.0cheesecake" introductionVersion:""
introductionVersion:"5" introductionVersion:" "
introductionVersion:"5blueberry" introductionVersion:"-"
introductionVersion:"--"
introductionVersion:"51.0cheesecake" deprecationVersion:"7.0.0"
introductionVersion:"50..0.1-cheesecake"
introductionVersion:"15"
introductionVersion:"54blueberry"
introductionVersion:"5-lasagna" 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 EOL
} }
ERROR=0 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-]+)?" # note that our semver is not fully compliant because we do not have a patch version for new envvars
ALPHA_REGEX="[A-Za-z]+[A-Za-z0-9-]*" # 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 # 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") QUERY_INTRO=$(echo "${QI}" | sed "s#\"\`#\"\`\n#g")
RESULTS_INTRO=$(echo "${QUERY_INTRO}"|wc -l)
echo "Checking introductionVersion annotations" echo "Checking introductionVersion annotations"
if [ "${QUERY_INTRO}" != "" ] && [ "${RESULTS_INTRO}" -gt 0 ]; then if [ "${QUERY_INTRO}" != "" ] && [ "${RESULTS_INTRO}" -gt 0 ]; then
echo echo
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 echo
echo "$QUERY_INTRO" echo "$QUERY_INTRO"
echo echo
echo ${GREEN}"${RESULTS_INTRO} items found"${NORM}
echo
print_introduction_version_examples print_introduction_version_examples
echo echo
ERROR=1 ERROR=1
@@ -64,11 +80,13 @@ else
echo echo
fi fi
# The following grep will filter out every line containing an `env` annotation # the following grep will filter out every line containing an `env` annotation and
# it will ignore every line that has allready a valid `desc` annotation # 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) RESULTS_DESC=$(echo "${QUERY_DESC}"|wc -l)
echo "Checking description annotations" echo "Checking description annotations"
@@ -76,9 +94,11 @@ echo "Checking description annotations"
if [ "${QUERY_DESC}" != "" ] && [ "${RESULTS_DESC}" -gt 0 ]; then if [ "${QUERY_DESC}" != "" ] && [ "${RESULTS_DESC}" -gt 0 ]; then
echo echo
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 "==============================================================================================="
echo "$QUERY_DESC" echo "$QUERY_DESC"
echo
echo ${GREEN}"${RESULTS_DESC} items found"${NORM}
ERROR=1 ERROR=1
else else
echo "All description annotations are valid" 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 ### 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 >}} {{< hint info >}}
* During development, set `introductionVersion` to a short, **alphabetic code name** that represents the upcoming release (e.g. `releaseX`). * 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. * This identifier stays constant until the release receives its final production semantic-version number.
{{< /hint >}} * 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 >}} * See the [Set the Correct IntroductionVersion]({{< ref "./new-release-process/" >}}) documentation before starting a new release candidate.
A new production version **MUST NOT** contain any alphabetic identifyers but the semantic version only.
{{< /hint >}}
### Adding Envvars to Existing Ones ### 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 ### 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:\ * From the ocis root run:\
`sudo make docs-clean`\ `sudo make docs-clean`\
`make docs-generate`\ `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.\ * 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`. * 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 ## 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 ### Maintain the 'env_vars.yaml' File
This is **mandatory for a new release** ! This is **mandatory for a new release** !
@@ -38,17 +51,13 @@ This is **mandatory for a new release** !
`sudo make docs-clean`\ `sudo make docs-clean`\
`make docs-generate`\ `make docs-generate`\
Any changes in `env_vars.yaml` are now considered. 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 >}} {{< hint info >}}
Note that due to how the code is currently designed, **things may get shifted** around though no real changes have been introduced. Note that due to how the code is currently designed, **things may get shifted** around though no real changes have been introduced.
{{< /hint >}} {{< /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" >}}). * With a new branch, remove all envvars from the `env_vars.yaml` file manually that have formerly been deprecated **and removed** from the code.
* 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.
* Commit the changes and merge it.\ * 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 ### Create Envvar Delta Files