Deltas Between Versions
This section provides information about added
, removed
and deprecated
environment variables between two major/minor versions.
- When creating a new release, this step should be completed before the new
stable-x.y
branch is created. Then, all changes will go cleanly into this stable branch.- If the changes required are not part of the stable branch created for the release process, you must backport all
added
,removed
anddeprecated
files created from the described process below into the stable branch. Backportingenv_vars.yaml
to the stable branch is not required and can be omitted.
To create the changed envvar tables, you must proceed the following steps in order:
-
Install, if not already done, the converter for adoc to markdown tables:
npm install -g downdoc
This is only required when converting adoc to markdown tables but it is highly recommended to show them in the dev docs too! -
Run
make -C docs docs-generate
from the ocis root.
A file namedenv_vars.yaml
is generated. Check for validity. If issues are found, fix them in the service sources first which need to be merged before you rerun make. For details how to do so, see Maintain the ’env_vars.yaml’ File. Any delta information is based on an actualenv_vars.yaml
file which is pulled from master by the python script described below! -
Configure the Python script
docs/helpers/changed_envvars.py
variables for the new version.
Note that you must use semver and not code names! -
Run the python script from the ocis root such as
python3 docs/helpers/changed_envvars.py
.
Note that the script pulls data from the master branch as base reference, therefore theenv_vars.yaml
file MUST be up to date.
adoc tables will be generated which are used for the admin docs and are the basis for markdown. -
Because the script can not determine the link target in the
Service
column, you must manually adapt them in the generated adoc files with respect to the name and target. Only one entry per identical service block is required, delete the cell content for the rest for ease of readability. See existing files for an example. -
Run
npx downdoc <filename.adoc>
for each of the newly generatedadded
,removed
anddeprecated
files. This will generate markdown files for the dev docs. -
Add in each markdown file on top the following sentence:
Note that the links provided in the service column are non functional when clicked.
, including a newline. -
Create a PR and merge it.