mirror of
https://github.com/opencloud-eu/opencloud.git
synced 2025-12-31 01:10:20 -06:00
update
This commit is contained in:
Martin Mattel
@@ -154,58 +154,68 @@ This yaml file can later be manually edited to add descriptions, default values,
|
||||
|
||||
The process further picks up the `yaml` file generated in the `Extract Rogue Envvars` step and renders it to an adoc file (a table is created) using a go template. The template file for this step can be found at `docs/templates/ADOC_extended.tmpl`.
|
||||
|
||||
## Tasks for New Releases
|
||||
## Doc Tasks for New Releases
|
||||
|
||||
**IMPORTANT**\
|
||||
For a new ocis release, some tasks are necessary to be done **before** and **after** releasing. Follow the steps carefully to avoid issues. Most of the docs related tasks are not part of the CI. With each step finished successfully, the next step can be started. Sometimes, due to last minute changes, steps need to be redone!
|
||||
|
||||
**Backgroud Information**\
|
||||
Admin docs rely on the existance of following branches in the ocis repo. Note that the reference in the admin docs which ocis branch is accessed is defined in the `antora.yml` file via `attributes` existing in each branch.
|
||||
Admin docs rely on the existance of the following branches in the ocis repo. Note that the reference in the admin docs which ocis branch is accessed is defined in the `antora.yml` file via `attributes` existing in each branch.
|
||||
|
||||
* `docs`\
|
||||
This reflects ocis master and is referenced from the admin docs from the master branch showing as `next`
|
||||
This reflects ocis master and is referenced from the admin docs from the master branch showing as `next` in the documentation.
|
||||
* `docs-stable-x.y`\
|
||||
This reflects a published ocis release and is referenced from the admin docs from the corresponding branch showing like `7.0`
|
||||
|
||||
Because of this, branching and parametrizing admin docs occurs **after** branching an ocis release with its necessary branches! If you branch admin docs before the required ocis branches are available, you must set the ocis source branch to import data from to `docs` and reconfigure afterwards.
|
||||
|
||||
**Notes**
|
||||
* When docs relevant data will be generated in ocis, the will be written into the `docs/servcies/...` folder structure, but they are in the master branch. When merging, an automated process will move them into the `docs`branch. When running make commands locally, the relocation is not done and files reside on the generated location!
|
||||
* When docs relevant data will be generated in ocis, they will be written into the `docs/servcies/...` folder structure, but they are in the master branch. When merging, an automated process will move/copy them into the `docs`branch. When running make commands locally, the relocation is not done and files reside on the generated location!
|
||||
|
||||
* .adoc file generation
|
||||
* Service related adoc files are saved during generation in `/docs/services/<service-name>` but will be relocated into the docs branch into a subfolder named `services/_include/adoc/<service-name.adoc>`.
|
||||
* Release based envvar changes are saved during generation in `/docs/services/general-info/env-var-deltas/<filename>` but will be relocated into the doc branch into a subfolder named `services/_include/adoc/env-var-deltas/<filename>`.
|
||||
* Service related adoc files are autogenerated and saved in `/docs/services/<service-name>` but will be _relocated_ by each merge into the docs branch into a subfolder named `services/_include/adoc/<service-name.adoc>`.
|
||||
* Release based envvar changes are saved during manual generation in `/docs/services/general-info/env-var-deltas/<filename>` but will be _copied_ on each merge into the doc branch into a subfolder named `services/_include/adoc/env-var-deltas/<filename>`.
|
||||
|
||||
* Exclude paths for Hugo
|
||||
* The paths defined above for .adoc files are excluded from parsing by Hugo. The source of what to exclude is defined in the `config.yaml` file located in [github.io](https://github.com/owncloud/owncloud.github.io/). Any folder containg .adoc files must be added there else `make -C docs docs-serve` or CI will fail reporting an adoc related parsing error. (We could also add an asciidoc parser to Hugo as alternative...)
|
||||
|
||||
### Task List
|
||||
|
||||
The following can be done at any time but it must be done *latest* when no envvar changes are made which is just before a new release gets published. The data generated **must** be part of the upcoming release and be merged therefore!
|
||||
The following can be done at any time but it must be done *latest* when no envvar changes are made which is just before a new release gets finally tagged. The data generated **must** be part of the upcoming release and be merged before tagging/branching!
|
||||
|
||||
**Before Releasing** Generate required .adoc files necessary for the admin docs
|
||||
|
||||
* Run from the ocis root `make -C docs docs-generate`
|
||||
* **Check for Extended Envvars**\
|
||||
Check if there is a change in the `extended-envars.yaml` output. In this case, process [Extended Envvars](#extended-envvars). When done, re-run the make command and check if the output of `./docs/services/_includes/adoc/extended_configvars.adoc` matches the expectations.
|
||||
* **Check for a changed 'env_vars.yaml' File**\
|
||||
This file will most likely show changes.
|
||||
This file will most likely show changes and merging them is essential as base for added/removed or deprecated envvars. This file will get additions/updates only, but things never get automatically deleted.
|
||||
* **Mandatory for a new release**, remove all envvars from the `env_vars.yaml` file manually that have been removed from the code, either with or without deprecation.
|
||||
|
||||
Commit the changes, create a PR and merge it. Next steps are based on this!
|
||||
|
||||
Only in case of a new release, **remove** all envvars that have been
|
||||
* Create added/removed and deprecated envvar .adoc files between versions containing includable tables pulled by the admin docs.
|
||||
* Parametrize variables in `docs/helpers/changed_envvars.py` according your needs necessary to generate proper output.
|
||||
* Create a branch and run from the ocis root `python3 docs/helpers/changed_envvars.py`\
|
||||
This will create three files that need manual treatment before committing/merging. Note that this script accesses sources from github and not locally, therefore an actual `env_vars.yaml` in github is essential.
|
||||
* Check the output of all three files and fix/delete any envvar in `env_vars.yaml` if required. If fixes have been done, the changed `env_vars.yaml` file **MUST** be _merged_ first, you must rebase and rerun the python script.
|
||||
* If all three files contain correct data, manually set the xrefs. This cant be done automatically. Use one of the existing `added` files as template to generate a consistent output.
|
||||
* Merge the three files and rerun the python script to prove all has been done correctly. You should now see only changes in xrefs as they get overwritten by default data. If this is the case, you can safely drop the generated changes.
|
||||
|
||||
2. In `./docs/helpers` run: `go run . --help` This will give you an overview of available commands.
|
||||
1. Run `go run . all` to generate and/or update required base files.\
|
||||
→ Any change in `env_vars.yaml` must be check out to be available in master.
|
||||
2. Create delta files for added, removed and deprecated envvars. To do so type:\
|
||||
`go run . env-var-delta-table` and use as parameter the versions you want to compare. Example: `v5.0.0 v6.0.0`.
|
||||
3. List and check the files created in `./docs/helpers/output/env-deltas/`. These are the files defining a table in markdown and asciidoc where the former is used in the dev docs and the latter is consumed by the admin docs build process.\
|
||||
**Important**: To make the files consumable, the following attribute must be changed in the respective admin docs respective branch definition: [docs-ocis/antora.yml](https://github.com/owncloud/docs-ocis/blob/master/antora.yml) `env_var_delta_name`. Only the delta filename part needs to be used. The complete filenames will be assembled automatically.
|
||||
```
|
||||
v5.0.0-v6.0.0 -->
|
||||
|
||||
v5.0.0-v6.0.0-added.md
|
||||
v5.0.0-v6.0.0-deprecated.md
|
||||
v5.0.0-v6.0.0-removed.md
|
||||
```
|
||||
**After Releasing** Generate required .md files necessary for the dev docs
|
||||
|
||||
3. Commit all changes, create a PR and post merging, adapt, if necessary, the ocis admin docs. With any merge in the admin docs, the newly created content for that ocis admin docs branch will be consumed.
|
||||
Similar to the Asciidoc files for the admin docs, Markdown files necessary for the dev docs need to be generated. The program for this is written in go and currently does not compare versions but only checks the introduction version. This is sufficient for devs as details necessary for migration documentation is done via the .adoc files in the admin docs.
|
||||
|
||||
* In `./docs/helpers` run: `go run . --help`\
|
||||
This will give you an overview of available commands.
|
||||
* Because `env_vars.yaml` has been cleaned up as part of the _before release_ tasks above, we can rely on its actuality for the branches to be compared.
|
||||
* Create delta files for added, removed and deprecated envvars. To do so type:\
|
||||
`go run . env-var-delta-table` and use as parameter the versions you want to compare. Example: `v5.0.0 v7.0.0`.
|
||||
* List and check the files created in `./docs/helpers/output/env-deltas/`. The markdown files created contain a table with dev relevant data. Any other files created are not relevant and can safely be deleted.
|
||||
* Create a branch and move the markdown files from `./docs/helpers/output/env-deltas/` to `./docs/services/general-info/env-var-deltas/`. The markdown files will be consumed by dev docs from this location.
|
||||
|
||||
|
||||
* Commit all changes, create a PR and merge. Dev docs is now up-to-date.
|
||||
|
||||
## Backporting
|
||||
|
||||
|
||||
@@ -0,0 +1 @@
|
||||
see docs/helpers/README.md#doc-tasks-for-new-releases for details how to create the necessary .adoc and .md files
|
||||
@@ -1,46 +0,0 @@
|
||||
make the markdown a asciidoc table
|
||||
|
||||
cp 4.0.0-5.0.0.md 4.0.0-5.0.0.adoc copy file
|
||||
sed -i 's/.$//g' 4.0.0-5.0.0.adoc remove last character of each line which is |
|
||||
sed -i 's/ \+//g' 4.0.0-5.0.0.adoc remove any double spaces
|
||||
fully remove the line containing |----...|
|
||||
rename: | File| Variable| Description| Default --> | Service| Variable| Description| Default
|
||||
|
||||
add on top under the page heading:
|
||||
[width="100%",cols="~,~,~,~",options="header"]
|
||||
|===
|
||||
|
||||
and at the bottom
|
||||
|===
|
||||
|
||||
check SSE_HTTP_ADDR and SSE_HTTP_ROOT, there is one | too much
|
||||
check WEB_OPTION_LOGIN_URL, there is one | missing
|
||||
check WEB_OPTION_DISABLED_EXTENSIONS, in the line before, there is one | too much
|
||||
|
||||
|
||||
sed -i "s/\;/\` \+\n\`/g" 4.0.0-5.0.0.adoc make each envvar a single line for ease of readability
|
||||
sed -i "s/\`|/\`\n|/g" 4.0.0-5.0.0.adoc put the next | after the last envvar in a line into a new line
|
||||
sed -i "s/|| \`/|\n|\`/g" 4.0.0-5.0.0.adoc split the || before an envvar into two lines
|
||||
sed -i "s/services\/(.*)\//xref\:\{s-path\}\/\1\.adoc/g" 4.0.0-5.0.0.adoc make "service" a xref
|
||||
|
||||
sed -i "s/\(services\/\)\(.*\)\(\/pkg\/config\/config.go\)/xref\:\{s-path\}\/\2.adoc\[\2\]/g" 4.0.0-5.0.0.adoc
|
||||
sed -i "s/\(services\/\)\(.*\)\(\/pkg\/config\/reva.go\)/xref\:\{s-path\}\/\2.adoc\[\2\]/g" 4.0.0-5.0.0.adoc
|
||||
sed -i "s/\(services\/\)\(.*\)\(\/pkg\/config\/debug.go\)/xref\:\{s-path\}\/\2.adoc\[\2\]/g" 4.0.0-5.0.0.adoc
|
||||
sed -i "s/\(services\/\)\(.*\)\(\/pkg\/config\/log.go\)/xref\:\{s-path\}\/\2.adoc\[\2\]/g" 4.0.0-5.0.0.adoc
|
||||
sed -i "s/\(services\/\)\(.*\)\(\/pkg\/config\/tracing.go\)/xref\:\{s-path\}\/\2.adoc\[\2\]/g" 4.0.0-5.0.0.adoc
|
||||
sed -i "s/\(services\/\)\(.*\)\(\/pkg\/config\/cache.go\)/xref\:\{s-path\}\/\2.adoc\[\2\]/g" 4.0.0-5.0.0.adoc
|
||||
sed -i "s/\(services\/\)\(.*\)\(\/pkg\/config\/content.go\)/xref\:\{s-path\}\/\2.adoc\[\2\]/g" 4.0.0-5.0.0.adoc
|
||||
sed -i "s/\(services\/\)\(.*\)\(\/pkg\/config\/search.go\)/xref\:\{s-path\}\/\2.adoc\[\2\]/g" 4.0.0-5.0.0.adoc
|
||||
sed -i "s/\(services\/\)\(.*\)\(\/pkg\/config\/options.go\)/xref\:\{s-path\}\/\2.adoc\[\2\]/g" 4.0.0-5.0.0.adoc
|
||||
services/antivirus/pkg/config/config.go --> xref:{s-path}/antivirus.adoc[antivirus]
|
||||
|
||||
change: ocis-pkg/shared/shared_types.go --> Available in multiple services
|
||||
|
||||
sed -i "s/\]|/\]\n|/g" 4.0.0-5.0.0.adoc put tab separator of service and envvar into a new line
|
||||
sed -i "s/|\`/| \`/g" 4.0.0-5.0.0.adoc |`OCIS --> | `OCIS
|
||||
|
||||
sed -i 's/\.\./\./g' 4.0.0-5.0.0.adoc remove trailing double dots in sentences
|
||||
|
||||
manually fix (remove) any double occurrences if a service like clientlog, auth-service, graph, ocm, policies, postprocessing, search, sse. this is because the origin path points to different go routines inside the same service.
|
||||
|
||||
manually checking the result and fixing issues (mostly minor) is mandatory
|
||||
@@ -1,7 +0,0 @@
|
||||
it is most easiest to create the added/removed/deprecated adoc tables using
|
||||
the python script in docs/helpers/changes_envvars.py
|
||||
|
||||
the script creates based on variables that need to be adapted according your needs
|
||||
all files necessary. finally you only MUST handle xrefs manually, see existing files
|
||||
for an example for how to do so.
|
||||
|
||||
Reference in New Issue
Block a user