diff --git a/antora-extensions/prerelease-attribute.js b/antora-extensions/prerelease-attribute.js new file mode 100644 index 0000000..fb54763 --- /dev/null +++ b/antora-extensions/prerelease-attribute.js @@ -0,0 +1,64 @@ +'use strict' + +/** + * Set the AsciiDoc attribute `page-component-version-is-prerelease` on every page + * of a component version that is marked `prerelease` in its antora.yml. + * + * Antora derives `page-component-version-is-latest` from the content catalog but + * has no counterpart for the prerelease flag (see computePageAttrs() in + * @antora/asciidoc-loader/lib/load-asciidoc.js), so content cannot ask "am I the + * dev line?" without hard-coding the version number -- which then rots at every + * version rollover. This extension closes that gap by reading the flag off the + * component version object in the content catalog, the same source Antora itself + * uses for `latest`, and exposing it to pages, partials and nav files: + * + * ifdef::page-component-version-is-prerelease[] + * This documents a version that is still in development. + * endif::[] + * + * The attribute is also visible to the UI templates as + * `page.attributes.[component-version-is-prerelease]` (the page composer drops the + * `page-` prefix when it builds the UI model). + * + * Value semantics follow Antora's `page-component-version-is-latest`: the + * attribute is set to the empty string when the version is a prerelease and is + * absent otherwise -- it is a flag for ifdef/ifndef, not a label. Use + * `page-component-display-version` for the visible marker (`8.3 (dev)` here). + * + * Because the attribute is derived, it is authoritative: if an antora.yml sets it + * by hand on a version that is NOT a prerelease, the value is dropped and a + * warning logged, so a stale hand-written flag cannot outlive the release it was + * added for. + */ +const ATTRIBUTE = 'page-component-version-is-prerelease' + +module.exports.register = function () { + const logger = this.getLogger('prerelease-attribute-extension') + + this.once('contentClassified', ({ contentCatalog, siteAsciiDocConfig }) => { + contentCatalog.getComponents().forEach((component) => { + component.versions.forEach((componentVersion) => { + // NOTE when a component descriptor defines no AsciiDoc attributes of its + // own, componentVersion.asciidoc IS the shared siteAsciiDocConfig object + // (classify-content.js returns it unchanged). Never mutate it in place -- + // that would leak this component version's flag into every other one. + const asciidoc = componentVersion.asciidoc || siteAsciiDocConfig || {} + const isPrerelease = !!componentVersion.prerelease + if (!isPrerelease && !(asciidoc.attributes && ATTRIBUTE in asciidoc.attributes)) return + const attributes = Object.assign({}, asciidoc.attributes) + if (isPrerelease) { + attributes[ATTRIBUTE] = '' + } else { + delete attributes[ATTRIBUTE] + logger.warn( + 'Removed hand-set %s from %s@%s: the version is not marked prerelease in its antora.yml.', + ATTRIBUTE, + componentVersion.version || '~', + componentVersion.name + ) + } + componentVersion.asciidoc = Object.assign({}, asciidoc, { attributes }) + }) + }) + }) +} diff --git a/content/ocis/8.0/antora.yml b/content/ocis/8.0/antora.yml index 4a2db0b..e651a54 100644 --- a/content/ocis/8.0/antora.yml +++ b/content/ocis/8.0/antora.yml @@ -71,4 +71,8 @@ asciidoc: ocis_services_env_var_deltas_path: '/services/general-info/envvars/env-var-deltas/' # used in depl-examples - download-gh-directory-url: https://download-directory.github.io + download-gh-directory-url: 'https://download-directory.github.io' + + # the url to download ocis + # note that this is inactive but required in the migration section for upgrading old binaries which do not longer exist. + ocis-downloadpage-url: 'https://download.owncloud.com/ocis/ocis' diff --git a/content/ocis/8.0/modules/admin/pages/deployment/general/general-info.adoc b/content/ocis/8.0/modules/admin/pages/deployment/general/general-info.adoc index 4a0a4c0..bf5e846 100644 --- a/content/ocis/8.0/modules/admin/pages/deployment/general/general-info.adoc +++ b/content/ocis/8.0/modules/admin/pages/deployment/general/general-info.adoc @@ -630,7 +630,7 @@ This is the local path the where Infinite Scale stores all data except the confi This is the local path where the Infinite Scale configuration is stored. When listing the content, you must see the file `ocis.yaml`. See the important information when using xref:docker-volumes[Docker Volumes]. * `` + -The Infinite Scale version used like `latest` or `{ocis-actual-version}` or ... . +The Infinite Scale version used like `latest` or `{page-component-latest-version}` or ... . + -- [source,bash] diff --git a/content/ocis/8.0/modules/admin/partials/depl-examples/ubuntu-compose/shared-setup.adoc b/content/ocis/8.0/modules/admin/partials/depl-examples/ubuntu-compose/shared-setup.adoc index 3f8b11a..265d181 100644 --- a/content/ocis/8.0/modules/admin/partials/depl-examples/ubuntu-compose/shared-setup.adoc +++ b/content/ocis/8.0/modules/admin/partials/depl-examples/ubuntu-compose/shared-setup.adoc @@ -250,7 +250,7 @@ NOTE: The client that downloads the example is not the server that you upload to NOTE: The client from which you download the example via a browser and upload it using `scp` must have access to the server and have the `scp` application installed. -To download and extract the necessary deployment example footnote:[Derived from the {compose_url}{compose_version}{compose_final_path}/{ocis_wopi}/[{ocis_wopi}, window=_blank] developer example], *open a browser* and enter the following URL. Note that this link also contains patches for release: `{ocis-actual-version}`. +To download and extract the necessary deployment example footnote:[Derived from the {compose_url}{compose_version}{compose_final_path}/{ocis_wopi}/[{ocis_wopi}, window=_blank] developer example], *open a browser* and enter the following URL. Note that this link also contains patches for release: `{page-component-version}`. //[source,url,subs="attributes+,+macros"] //---- diff --git a/content/ocis/8.1/antora.yml b/content/ocis/8.1/antora.yml index 4c87eb5..52b7028 100644 --- a/content/ocis/8.1/antora.yml +++ b/content/ocis/8.1/antora.yml @@ -7,45 +7,19 @@ nav: asciidoc: attributes: - # with antora 3.2, there will be new attributes `antora-component-version` and `antora-component-name` - # the ones used below need to be replaced when antora has been updated to 3.2 - # https://gitlab.com/antora/antora/-/merge_requests/1048/diffs - latest-ocis-version: {page-component-version} # do not change, this is the value of the version key - previous-ocis-version: {page-component-version} # do not change, this is the value of the version key - - # must be removed when antora 3.2 has been updated, because this is then an intrinsic attribute - # the branched value is the value for the production release like 'next' or '7.1' - antora-component-version: '8.1' - # used to define the include path for services without trailing / # note that any changes of this path also need adjustment in # https://github.com/owncloud/ocis-charts/tree/master/charts/ocis/docs s-path: 'deployment/services/s-list' # the name of the sub directory that defines the sources folder used in the compose deployment examples - ocis_wopi: ocis_full - - # note that service_url_component is used for services ONLY - # service_url_component will be used to assemble the url for services to include content (tables) - # sourced from the ocis repo. - # 'docs' for the next branch or 'docs-stable-7.2' for a production branch - service_url_component: 'docs-stable-8.1' - - # defines the url path component when accessing the ocis repo for versioned data includes or examples - # 'master' for the next branch or 'stable-7.2' for a production branch - # example: {compose_url}{ocis_repo_url_component}{compose_final_path} - ocis_repo_url_component: 'stable-8.1' - - # this always points to the latest stable branch such as 'stable-7.2' - # this branch also includes patches if any - # used for links where you would else download from master but the content better comes from stable - ocis_repo_url_stable: 'stable-8.1' + ocis_wopi: 'ocis_full' - # service_tab_text will be used as tab text shown for the tables in services only - # note when literally changing the word 'master' to something else, you also must adapt 'env-and-yaml.adoc'. - # this does not apply to branched releases using semver, only to the master branch! - # 'master' for the next branch or '7.2.0' for a production branch including patch releases like `7.2.1' - service_tab_text: '8.1.0' + ocis_helpers: 'ocis_helpers' # note the preceding 'example$' (family coordinate) cant be used as part of the attribute + ocis_helpers_adoc: '{ocis_helpers}/adoc/' + ocis_helpers_env_var_deltas: '{ocis_helpers}/env_var_deltas/' + ocis_helpers_extended: '{ocis_helpers}/extended/' + ocis_helpers_yaml: '{ocis_helpers}/yaml/' # this is the first part of the name for envvars between major versions that will be added or removed # example for full name: 7.0.0-7.1.0-added.adoc or 7.0.0-7.1.0-removed.adoc @@ -54,21 +28,20 @@ asciidoc: # set attributes defining path components which will be assembled in the document compose_url: 'https://github.com/owncloud/ocis/tree/' - compose_raw_url: 'https://raw.githubusercontent.com/owncloud/ocis/' + compose_raw_url: 'https://raw.githubusercontent.com/owncloud/ocis/refs/heads/' compose_final_path: '/deployments/examples' - # production and rolling have separate paths when it comes to download from docker - docker_ocis_prod_url: https://hub.docker.com/r/owncloud/ocis - docker_ocis_rolling_url: https://hub.docker.com/r/owncloud/ocis-rolling - # only used in deployment/services via partials/env-and-yaml.adoc # static path components, used to assemble the final path dependent on service_url_component to include services - ocis_services_raw_url: 'https://raw.githubusercontent.com/owncloud/ocis/' - ocis_services_final_path: '/services/_includes/' + ocis_services_raw_url: 'https://raw.githubusercontent.com/owncloud/ocis/refs/heads/' - # only used in deployment/services/env-var-changes.adoc - # static path component, used to assemble the final path - ocis_services_env_var_deltas_path: '/services/general-info/envvars/env-var-deltas/' + # production and rolling have separate paths when it comes to download from docker + docker_ocis_prod_url: 'https://hub.docker.com/r/owncloud/ocis' + docker_ocis_rolling_url: 'https://hub.docker.com/r/owncloud/ocis-rolling' # used in depl-examples - download-gh-directory-url: https://download-directory.github.io + download-gh-directory-url: 'https://download-directory.github.io' + + # the url to download ocis + # note that this is inactive but required in the migration section for upgrading old binaries which do not longer exist. + ocis-downloadpage-url: 'https://download.owncloud.com/ocis/ocis' diff --git a/content/ocis/8.1/modules/admin/pages/depl-examples/ubuntu-compose/ubuntu-compose-hetzner.adoc b/content/ocis/8.1/modules/admin/pages/depl-examples/ubuntu-compose/ubuntu-compose-hetzner.adoc index 02c7b39..a68b24f 100644 --- a/content/ocis/8.1/modules/admin/pages/depl-examples/ubuntu-compose/ubuntu-compose-hetzner.adoc +++ b/content/ocis/8.1/modules/admin/pages/depl-examples/ubuntu-compose/ubuntu-compose-hetzner.adoc @@ -23,7 +23,7 @@ IMPORTANT: By choosing https://www.hetzner.com[Hetzner] for our cloud deployment NOTE: With the minimum configuration available on Hetzner, you can start with about €4/month for a cloud driven Infinite Scale deployment. Note that prices are subject to changes and only intended for informational purposes. -NOTE: This guide references the latest {version-type} version of Infinite Scale. +NOTE: This guide references the latest stable version of Infinite Scale. NOTE: With this setup, each deployment only contains one instance of Infinite Scale. diff --git a/content/ocis/8.1/modules/admin/pages/depl-examples/ubuntu-compose/ubuntu-compose-prod.adoc b/content/ocis/8.1/modules/admin/pages/depl-examples/ubuntu-compose/ubuntu-compose-prod.adoc index 8e53c66..4a5ce55 100644 --- a/content/ocis/8.1/modules/admin/pages/depl-examples/ubuntu-compose/ubuntu-compose-prod.adoc +++ b/content/ocis/8.1/modules/admin/pages/depl-examples/ubuntu-compose/ubuntu-compose-prod.adoc @@ -25,7 +25,7 @@ toc::[] IMPORTANT: *There are several decisions and steps that need to be taken when setting up and configuring the server. We strongly recommend that you read the manual and not just try to copy and paste commands.* -NOTE: This guide references the latest {version-type} version of Infinite Scale. +NOTE: This guide references the latest stable version of Infinite Scale. NOTE: With this setup, each deployment only contains one instance of Infinite Scale. diff --git a/content/ocis/8.1/modules/admin/pages/deployment/general/general-info.adoc b/content/ocis/8.1/modules/admin/pages/deployment/general/general-info.adoc index 4a0a4c0..bf5e846 100644 --- a/content/ocis/8.1/modules/admin/pages/deployment/general/general-info.adoc +++ b/content/ocis/8.1/modules/admin/pages/deployment/general/general-info.adoc @@ -630,7 +630,7 @@ This is the local path the where Infinite Scale stores all data except the confi This is the local path where the Infinite Scale configuration is stored. When listing the content, you must see the file `ocis.yaml`. See the important information when using xref:docker-volumes[Docker Volumes]. * `` + -The Infinite Scale version used like `latest` or `{ocis-actual-version}` or ... . +The Infinite Scale version used like `latest` or `{page-component-latest-version}` or ... . + -- [source,bash] diff --git a/content/ocis/8.1/modules/admin/pages/deployment/services/env-var-changes.adoc b/content/ocis/8.1/modules/admin/pages/deployment/services/env-var-changes.adoc index ed8ce2a..3897302 100644 --- a/content/ocis/8.1/modules/admin/pages/deployment/services/env-var-changes.adoc +++ b/content/ocis/8.1/modules/admin/pages/deployment/services/env-var-changes.adoc @@ -1,17 +1,14 @@ # Changed Environment Variables in Versions :toc: right -:description: This page contains tables with added and removed environment variables between Infinite Scale version 7.3.0 and 8.0.0. +:description: This page contains tables with added and removed environment variables between Infinite Scale version 8.0.0 and 8.1.0. :page-aliases: ROOT:deployment/services/env-var-changes.adoc -:source_path: {ocis_services_raw_url}{service_url_component}{ocis_services_env_var_deltas_path} - //// to be set in antora.yml -ocis_services_raw_url: https://raw.githubusercontent.com/owncloud/ocis/ -service_url_component: docs || docs-stable-8.0 -ocis_services_env_var_deltas_path: /services/general-info/envvars/env-var-deltas/ -env_var_delta_name: 7.3.0-8.0.0 +ocis_helpers: example$ocis_helpers +ocis_helpers_env_var_deltas: {ocis_helpers}/env_var_deltas/ +env_var_delta_name: 8.3.0-8.2.0 //// == Introduction @@ -25,16 +22,16 @@ env_var_delta_name: 7.3.0-8.0.0 Added:: + -- -include::{source_path}{env_var_delta_name}-added.adoc[] +include::example${ocis_helpers_env_var_deltas}{env_var_delta_name}-added.adoc[] -- Removed:: + -- -include::{source_path}{env_var_delta_name}-removed.adoc[] +include::example${ocis_helpers_env_var_deltas}{env_var_delta_name}-removed.adoc[] -- Deprecated:: + -- -include::{source_path}{env_var_delta_name}-deprecated.adoc[] +include::example${ocis_helpers_env_var_deltas}{env_var_delta_name}-deprecated.adoc[] -- ==== diff --git a/content/ocis/8.1/modules/admin/pages/deployment/services/env-vars-special-scope.adoc b/content/ocis/8.1/modules/admin/pages/deployment/services/env-vars-special-scope.adoc index 2fef2fd..5ac231b 100644 --- a/content/ocis/8.1/modules/admin/pages/deployment/services/env-vars-special-scope.adoc +++ b/content/ocis/8.1/modules/admin/pages/deployment/services/env-vars-special-scope.adoc @@ -13,7 +13,6 @@ Examples: * The extended environment variable `OCIS_CONFIG_DIR` can be used with `ocis init`. * The special environment variable `OCIS_RUN_SERVICES` defines services to start when the container is started. - == Special Environment Variables // these envvars cant be gathered automatically and must be maintained manually. they change very rarely! @@ -24,23 +23,20 @@ The following environment variables are only available when using a developer ve include::partial$deployment/services/env-and-yaml.adoc[tag=special_envvars] - == Extended Environment Variables //// -IMPORTANT: extended envvars currently do not have an extended_deprecation.adoc file. handled in the include. +IMPORTANT: extended envvars currently do not have an extended_deprecation.adoc file. this is handled in the include. -note that if a description of an extended envvar missing or strange looking envvars present, you need to fix this in: -https://github.com/owncloud/ocis/blob/master/docs/helpers/extended_vars.yaml -see the readme.md file in that folder. +note that if a description of an extended envvar missing or strange looking envvars present, +you need to fix this via the ocis_helper executable in this repo. see the readme of the helper for details. //// :service_name: extended Note, see the xref:deployment/services/registry.adoc[Registry] documentation for details on the Micro Registry and their available settings. -include::partial$deployment/services/env-and-yaml.adoc[tag=envvars-only] - +include::partial$deployment/services/env-and-yaml.adoc[tag=extended-only] == Global Environment Variables @@ -50,4 +46,4 @@ include::partial$deployment/services/env-and-yaml.adoc[tag=envvars-only] Note that the descriptions of these environment variables may differ depending on the service context. -include::partial$deployment/services/env-and-yaml.adoc[tag=envvars-only] +include::partial$deployment/services/env-and-yaml.adoc[tag=global-only] diff --git a/content/ocis/8.1/modules/admin/pages/deployment/services/s-list/policies.adoc b/content/ocis/8.1/modules/admin/pages/deployment/services/s-list/policies.adoc index 5b836aa..3b2a1fc 100644 --- a/content/ocis/8.1/modules/admin/pages/deployment/services/s-list/policies.adoc +++ b/content/ocis/8.1/modules/admin/pages/deployment/services/s-list/policies.adoc @@ -164,12 +164,12 @@ The policies service contains a set of preconfigured example policies. See the d [tabs] ==== -{service_tab_text}:: +{tab_text}:: + -- {compose_url}{compose_version}{compose_final_path}[Rego policies deployment example directory,window=_blank] -Using git branch name: `{compose_version}`, to point to the latest stable version that also includes patches +Using git branch name: `{compose_version}`, to point to the latest stable version that also includes patches. -- ==== diff --git a/content/ocis/8.1/modules/admin/pages/deployment/webui/webui-theming.adoc b/content/ocis/8.1/modules/admin/pages/deployment/webui/webui-theming.adoc index 14c581c..e320750 100644 --- a/content/ocis/8.1/modules/admin/pages/deployment/webui/webui-theming.adoc +++ b/content/ocis/8.1/modules/admin/pages/deployment/webui/webui-theming.adoc @@ -42,7 +42,12 @@ Some theme keys are mandatory, like the `common.shareRoles` settings. Such manda == Configuring a Theme -.Sourced from https://github.com/owncloud/ocis/blob/{compose_version}{web_assets_path}theme.json[GitHub, _window=blank] +:configuring_add_on_text: +ifdef::page-component-version-is-prerelease[] +:configuring_add_on_text: from the latest stable version. +endif::[] + +.Sourced from https://github.com/owncloud/ocis/blob/{compose_version}{web_assets_path}theme.json[GitHub, _window=blank] {configuring_add_on_text} [source,json] ---- include::{ocis_services_raw_url}{compose_version}{web_assets_path}theme.json[] diff --git a/content/ocis/8.1/modules/admin/pages/deployment/wopi/wopi.adoc b/content/ocis/8.1/modules/admin/pages/deployment/wopi/wopi.adoc index db2fe47..c8fd68f 100644 --- a/content/ocis/8.1/modules/admin/pages/deployment/wopi/wopi.adoc +++ b/content/ocis/8.1/modules/admin/pages/deployment/wopi/wopi.adoc @@ -73,7 +73,7 @@ image::deployment/wopi/wopi-overview.svg[WOPI Overview Diagram,width=500] + [tabs] ==== -{service_tab_text}:: +{tab_text}:: + -- {compose_url}{compose_version}{compose_final_path}/{ocis_wopi}[Docker compose `ocis_full` deployment example directory,window=_blank] diff --git a/content/ocis/8.1/modules/admin/pages/index.adoc b/content/ocis/8.1/modules/admin/pages/index.adoc index 4c5309c..3ef114e 100644 --- a/content/ocis/8.1/modules/admin/pages/index.adoc +++ b/content/ocis/8.1/modules/admin/pages/index.adoc @@ -71,4 +71,4 @@ Configuration of Infinite Scale might be quite different to what you are used to == End-User License Agreement (EULA) -ownCloud provides an EULA to clarify, among various topics, who can use this software and which conditions apply to the groups of users defined. See the actual {compose_raw_url}{compose_version}/assets/End-User-License-Agreement-for-ownCloud-Infinite-Scale.pdf[EULA] for details. +ownCloud provides an EULA to clarify, among various topics, who can use this software and which conditions apply to the groups of users defined. See the actual {compose_raw_url}{ocis_git_version}/assets/End-User-License-Agreement-for-ownCloud-Infinite-Scale.pdf[EULA] for details. diff --git a/content/ocis/8.1/modules/admin/partials/depl-examples/ubuntu-compose/shared-setup.adoc b/content/ocis/8.1/modules/admin/partials/depl-examples/ubuntu-compose/shared-setup.adoc index 3f8b11a..87c004b 100644 --- a/content/ocis/8.1/modules/admin/partials/depl-examples/ubuntu-compose/shared-setup.adoc +++ b/content/ocis/8.1/modules/admin/partials/depl-examples/ubuntu-compose/shared-setup.adoc @@ -250,7 +250,14 @@ NOTE: The client that downloads the example is not the server that you upload to NOTE: The client from which you download the example via a browser and upload it using `scp` must have access to the server and have the `scp` application installed. -To download and extract the necessary deployment example footnote:[Derived from the {compose_url}{compose_version}{compose_final_path}/{ocis_wopi}/[{ocis_wopi}, window=_blank] developer example], *open a browser* and enter the following URL. Note that this link also contains patches for release: `{ocis-actual-version}`. +:note_text: +ifdef::page-component-version-is-prerelease[] +:note_text: There is no download for the ocis development version for stability reasons. The latest stable release {page-component-latest-version} is used instead. +endif::[] + +{note_text} + +To download and extract the necessary deployment example footnote:[Derived from the {compose_url}{compose_version}{compose_final_path}/{ocis_wopi}/[{ocis_wopi}, window=_blank] developer example], *open a browser* and enter the following URL. Note that this link also contains patches, if any, for the stable release branch: `{compose_version}`. //[source,url,subs="attributes+,+macros"] //---- @@ -329,7 +336,7 @@ Add a valid response eMail address for Letsencrypt, see the note below. Set the CAServer to staging, see the note below. * `OCIS_DOCKER_IMAGE` + -Check that the correct image type is selected ({version-type}). +Check that the correct image type is selected. * `OCIS_DOMAIN`, `COLLABORA_DOMAIN` and/or `ONLYOFFICE_DOMAIN` + Set the domain names as defined in xref:domain-names[Domain Names]. @@ -649,14 +656,10 @@ docker volume rm {ocis_wopi}_ocis-config {ocis_wopi}_ocis-data === Updating -// for testing only -//:version-type: rolling -//:version-type: production - Infinite Scale:: + -- -ifeval::["{version-type}" == "rolling"] +ifdef::page-component-version-is-prerelease[] For Infinite Scale rolling releases, the following steps are essential to avoid breaking the setup. This is because rolling releases depend on all updates being done in sequence. When new versions of Infinite Scale are available, you *may* skip any version between the one you are currently running and the latest available rolling release for internal update reasons. All versions must be downloaded and launched at once. For more details, see https://owncloud.dev/ocis/release_roadmap/#updating-and-overlap[Updating and Overlap] in the developer documentation. @@ -682,7 +685,7 @@ Note that we recommend manually checking to see if the deployment source has cha endif::[] -ifeval::["{version-type}" != "rolling"] +ifndef::page-component-version-is-prerelease[] Follow these steps to update between production releases: diff --git a/content/ocis/8.1/modules/admin/partials/deployment/services/env-and-yaml.adoc b/content/ocis/8.1/modules/admin/partials/deployment/services/env-and-yaml.adoc index b0f093d..f1c214a 100644 --- a/content/ocis/8.1/modules/admin/partials/deployment/services/env-and-yaml.adoc +++ b/content/ocis/8.1/modules/admin/partials/deployment/services/env-and-yaml.adoc @@ -15,7 +15,7 @@ Important: The xxx_deprecation.adoc does not exist for extended or global envvar tag::special_envvars[] // compute the correct tab text -include::partial$multi-location/tab-text.adoc[] +include::partial$multi-location/compose-version.adoc[] // this directive is usually not necessary and its need likely an antora bug. because there is no text after the include // and the tabs, we need to simulate this with empty. using it we prevent a warning that the attribute is missing... @@ -23,7 +23,7 @@ include::partial$multi-location/tab-text.adoc[] [tabs] ==== -{tab_text}:: +{env_tab_text}:: + -- [caption=] @@ -62,22 +62,22 @@ end::special_envvars[] tag::envvars-yaml[] // compute the correct tab text -include::partial$multi-location/tab-text.adoc[] +include::partial$multi-location/compose-version.adoc[] === Environment Variables The `{service_name}` service is configured via the following environment variables. Read the xref:deployment/services/envvar-types-description.adoc[Environment Variable Types] documentation for important details. Column `IV` shows with which release the environment variable has been introduced. // load the deprecation activation file. this will overwrite the above. -include::{ocis_services_raw_url}{service_url_component}{ocis_services_final_path}adoc/{service_name}_deprecation.adoc[] +include::example${ocis_helpers_adoc}{service_name}_deprecation.adoc[] [tabs] ==== -{tab_text}:: +{env_tab_text}:: + -- // if deprecation activation is true, it will also show the deprecation content. -include::{ocis_services_raw_url}{service_url_component}{ocis_services_final_path}adoc/{service_name}_configvars.adoc[] +include::example${ocis_helpers_adoc}{service_name}_configvars.adoc[] -- ==== @@ -88,12 +88,12 @@ include::{ocis_services_raw_url}{service_url_component}{ocis_services_final_path [tabs] ==== -{tab_text}:: +{env_tab_text}:: + -- [source,yaml] ---- -include::{ocis_services_raw_url}{service_url_component}{ocis_services_final_path}{service_name}-config-example.yaml[] +include::example${ocis_helpers_yaml}{service_name}-config-example.yaml[] ---- -- ==== @@ -101,16 +101,43 @@ include::{ocis_services_raw_url}{service_url_component}{ocis_services_final_path end::envvars-yaml[] +// TEXT VERSION 2 only print global envvars (no yaml available) -// TEXT VERSION 2 only print envvars +tag::global-only[] -tag::envvars-only[] +// default to not show deprecations +:show-deprecation: false + +// compute the correct tab text +include::partial$multi-location/compose-version.adoc[] + +The `{service_name}` variables are defined in the following way. Read the xref:deployment/services/envvar-types-description.adoc[Environment Variable Types] documentation for important details. Column `IV` shows with which release the environment variable has been introduced. + +// do not load any deprecation activations. use the default set via ':show-deprecation: false' above +// this prevents showing any deprecations which is necessary for global envvars which currently do not have +// any deprecations configured. + +[tabs] +==== +{env_tab_text}:: ++ +-- +include::example${ocis_helpers_adoc}{service_name}_configvars.adoc[] +-- +==== + +end::global-only[] + + +// TEXT VERSION 3 only print extended envvars (no yaml available) + +tag::extended-only[] // default to not show deprecations :show-deprecation: false // compute the correct tab text -include::partial$multi-location/tab-text.adoc[] +include::partial$multi-location/compose-version.adoc[] The `{service_name}` variables are defined in the following way. Read the xref:deployment/services/envvar-types-description.adoc[Environment Variable Types] documentation for important details. Column `IV` shows with which release the environment variable has been introduced. @@ -120,11 +147,11 @@ The `{service_name}` variables are defined in the following way. Read the xref:d [tabs] ==== -{tab_text}:: +{env_tab_text}:: + -- -include::{ocis_services_raw_url}{service_url_component}{ocis_services_final_path}adoc/{service_name}_configvars.adoc[] +include::example${ocis_helpers_extended}{service_name}_configvars.adoc[] -- ==== -end::envvars-only[] +end::extended-only[] diff --git a/content/ocis/8.1/modules/admin/partials/multi-location/compose-version.adoc b/content/ocis/8.1/modules/admin/partials/multi-location/compose-version.adoc index 81006a4..9a37a68 100644 --- a/content/ocis/8.1/modules/admin/partials/multi-location/compose-version.adoc +++ b/content/ocis/8.1/modules/admin/partials/multi-location/compose-version.adoc @@ -1,28 +1,25 @@ //// -depending of the version (production/rolling), attributes get defined dynamically +depending of the version (stable/development), attributes get defined dynamically -if the branch is master, identified via the component version equals 'next', we have a rolling release -if the branch is anything else, it is a production version and has its own branch +if the branch is master, identified via attribute page-component-version-is-prerelease, we must point to the latest stable +if the branch is anything else, it is a stable version and and can be used as is (stable-x.y) -the outcome guarantees that we always access the correct paths to get or reference source files from - -ocis_repo_url_component: defined in antora.yml: is either master or a branched version -ocis_repo_url_stable: defined in antora.yml: is always the latest stable branch of this version -antora-component-version: intrinsic via antora.yml: is either next or a branched version like 7.2 +the outcome guarantees that we always access the correct paths to get or reference to source files from //// -// first we define the default -// production (because it has an own doc branch) -// url is either master or like stable-7.2 -:compose_version: {ocis_repo_url_component} -:version-type: production +// first we define the default which is stable +// url assembled points to any valid stable-x.y +:compose_version: stable-{page-component-version} +:tab_text: {page-component-version} +:env_tab_text: {page-component-version} +:ocis_git_version: stable-{page-component-version} // but: -// if it is the master branch, defined as next, we need to redefine to a stable branch +// if it is the prerelease (master branch == development), we need to redefine to the latest stable branch // master may contain non functional data -// latest-ocis-version is defined in global-attributes.yml: 7.2 or 7.1 -// the file is included via an extension -ifeval::["{antora-component-version}" == "next"] -:compose_version: {ocis_repo_url_stable} -:version-type: rolling +ifdef::page-component-version-is-prerelease[] +:compose_version: stable-{page-component-latest-version} +:tab_text: {page-component-latest-version} +:env_tab_text: master +:ocis_git_version: master endif::[] diff --git a/content/ocis/8.1/modules/admin/partials/multi-location/tab-text.adoc b/content/ocis/8.1/modules/admin/partials/multi-location/tab-text.adoc deleted file mode 100644 index 3317e57..0000000 --- a/content/ocis/8.1/modules/admin/partials/multi-location/tab-text.adoc +++ /dev/null @@ -1,12 +0,0 @@ -//// -the tab text printed depends on if you are on master, then it is 'master + Rolling ' -or it is the value of the name as defined in antora.yml -//// - -// compute the correct tab text -:tab_text: {service_tab_text} - -// we do not make rolling releases anymore, keeping the code if that changes -// ifeval::["{service_tab_text}" == "master"] -// :tab_text: {service_tab_text} + Rolling {ocis-rolling-version} -// endif::[] diff --git a/content/ocis/8.2/antora.yml b/content/ocis/8.2/antora.yml index b408a2c..f81655c 100644 --- a/content/ocis/8.2/antora.yml +++ b/content/ocis/8.2/antora.yml @@ -7,45 +7,19 @@ nav: asciidoc: attributes: - # with antora 3.2, there will be new attributes `antora-component-version` and `antora-component-name` - # the ones used below need to be replaced when antora has been updated to 3.2 - # https://gitlab.com/antora/antora/-/merge_requests/1048/diffs - latest-ocis-version: {page-component-version} # do not change, this is the value of the version key - previous-ocis-version: {page-component-version} # do not change, this is the value of the version key - - # must be removed when antora 3.2 has been updated, because this is then an intrinsic attribute - # the branched value is the value for the production release like 'next' or '7.1' - antora-component-version: '8.2' - # used to define the include path for services without trailing / # note that any changes of this path also need adjustment in # https://github.com/owncloud/ocis-charts/tree/master/charts/ocis/docs s-path: 'deployment/services/s-list' # the name of the sub directory that defines the sources folder used in the compose deployment examples - ocis_wopi: ocis_full - - # note that service_url_component is used for services ONLY - # service_url_component will be used to assemble the url for services to include content (tables) - # sourced from the ocis repo. - # 'docs' for the next branch or 'docs-stable-7.2' for a production branch - service_url_component: 'docs-stable-8.2' - - # defines the url path component when accessing the ocis repo for versioned data includes or examples - # 'master' for the next branch or 'stable-7.2' for a production branch - # example: {compose_url}{ocis_repo_url_component}{compose_final_path} - ocis_repo_url_component: 'stable-8.2' - - # this always points to the latest stable branch such as 'stable-7.2' - # this branch also includes patches if any - # used for links where you would else download from master but the content better comes from stable - ocis_repo_url_stable: 'stable-8.2' + ocis_wopi: 'ocis_full' - # service_tab_text will be used as tab text shown for the tables in services only - # note when literally changing the word 'master' to something else, you also must adapt 'env-and-yaml.adoc'. - # this does not apply to branched releases using semver, only to the master branch! - # 'master' for the next branch or '7.2.0' for a production branch including patch releases like `7.2.1' - service_tab_text: '8.2.0' + ocis_helpers: 'ocis_helpers' # note the preceding 'example$' (family coordinate) cant be used as part of the attribute + ocis_helpers_adoc: '{ocis_helpers}/adoc/' + ocis_helpers_env_var_deltas: '{ocis_helpers}/env_var_deltas/' + ocis_helpers_extended: '{ocis_helpers}/extended/' + ocis_helpers_yaml: '{ocis_helpers}/yaml/' # this is the first part of the name for envvars between major versions that will be added or removed # example for full name: 7.0.0-7.1.0-added.adoc or 7.0.0-7.1.0-removed.adoc @@ -54,21 +28,20 @@ asciidoc: # set attributes defining path components which will be assembled in the document compose_url: 'https://github.com/owncloud/ocis/tree/' - compose_raw_url: 'https://raw.githubusercontent.com/owncloud/ocis/' + compose_raw_url: 'https://raw.githubusercontent.com/owncloud/ocis/refs/heads/' compose_final_path: '/deployments/examples' - # production and rolling have separate paths when it comes to download from docker - docker_ocis_prod_url: https://hub.docker.com/r/owncloud/ocis - docker_ocis_rolling_url: https://hub.docker.com/r/owncloud/ocis-rolling - # only used in deployment/services via partials/env-and-yaml.adoc # static path components, used to assemble the final path dependent on service_url_component to include services - ocis_services_raw_url: 'https://raw.githubusercontent.com/owncloud/ocis/' - ocis_services_final_path: '/services/_includes/' + ocis_services_raw_url: 'https://raw.githubusercontent.com/owncloud/ocis/refs/heads/' - # only used in deployment/services/env-var-changes.adoc - # static path component, used to assemble the final path - ocis_services_env_var_deltas_path: '/services/general-info/envvars/env-var-deltas/' + # production and rolling have separate paths when it comes to download from docker + docker_ocis_prod_url: 'https://hub.docker.com/r/owncloud/ocis' + docker_ocis_rolling_url: 'https://hub.docker.com/r/owncloud/ocis-rolling' # used in depl-examples - download-gh-directory-url: https://download-directory.github.io + download-gh-directory-url: 'https://download-directory.github.io' + + # the url to download ocis + # note that this is inactive but required in the migration section for upgrading old binaries which do not longer exist. + ocis-downloadpage-url: 'https://download.owncloud.com/ocis/ocis' diff --git a/content/ocis/8.2/modules/admin/pages/depl-examples/ubuntu-compose/ubuntu-compose-hetzner.adoc b/content/ocis/8.2/modules/admin/pages/depl-examples/ubuntu-compose/ubuntu-compose-hetzner.adoc index 02c7b39..a68b24f 100644 --- a/content/ocis/8.2/modules/admin/pages/depl-examples/ubuntu-compose/ubuntu-compose-hetzner.adoc +++ b/content/ocis/8.2/modules/admin/pages/depl-examples/ubuntu-compose/ubuntu-compose-hetzner.adoc @@ -23,7 +23,7 @@ IMPORTANT: By choosing https://www.hetzner.com[Hetzner] for our cloud deployment NOTE: With the minimum configuration available on Hetzner, you can start with about €4/month for a cloud driven Infinite Scale deployment. Note that prices are subject to changes and only intended for informational purposes. -NOTE: This guide references the latest {version-type} version of Infinite Scale. +NOTE: This guide references the latest stable version of Infinite Scale. NOTE: With this setup, each deployment only contains one instance of Infinite Scale. diff --git a/content/ocis/8.2/modules/admin/pages/depl-examples/ubuntu-compose/ubuntu-compose-prod.adoc b/content/ocis/8.2/modules/admin/pages/depl-examples/ubuntu-compose/ubuntu-compose-prod.adoc index 8e53c66..4a5ce55 100644 --- a/content/ocis/8.2/modules/admin/pages/depl-examples/ubuntu-compose/ubuntu-compose-prod.adoc +++ b/content/ocis/8.2/modules/admin/pages/depl-examples/ubuntu-compose/ubuntu-compose-prod.adoc @@ -25,7 +25,7 @@ toc::[] IMPORTANT: *There are several decisions and steps that need to be taken when setting up and configuring the server. We strongly recommend that you read the manual and not just try to copy and paste commands.* -NOTE: This guide references the latest {version-type} version of Infinite Scale. +NOTE: This guide references the latest stable version of Infinite Scale. NOTE: With this setup, each deployment only contains one instance of Infinite Scale. diff --git a/content/ocis/8.2/modules/admin/pages/deployment/general/general-info.adoc b/content/ocis/8.2/modules/admin/pages/deployment/general/general-info.adoc index 4a0a4c0..bf5e846 100644 --- a/content/ocis/8.2/modules/admin/pages/deployment/general/general-info.adoc +++ b/content/ocis/8.2/modules/admin/pages/deployment/general/general-info.adoc @@ -630,7 +630,7 @@ This is the local path the where Infinite Scale stores all data except the confi This is the local path where the Infinite Scale configuration is stored. When listing the content, you must see the file `ocis.yaml`. See the important information when using xref:docker-volumes[Docker Volumes]. * `` + -The Infinite Scale version used like `latest` or `{ocis-actual-version}` or ... . +The Infinite Scale version used like `latest` or `{page-component-latest-version}` or ... . + -- [source,bash] diff --git a/content/ocis/8.2/modules/admin/pages/deployment/services/env-var-changes.adoc b/content/ocis/8.2/modules/admin/pages/deployment/services/env-var-changes.adoc index ed8ce2a..f043914 100644 --- a/content/ocis/8.2/modules/admin/pages/deployment/services/env-var-changes.adoc +++ b/content/ocis/8.2/modules/admin/pages/deployment/services/env-var-changes.adoc @@ -1,17 +1,14 @@ # Changed Environment Variables in Versions :toc: right -:description: This page contains tables with added and removed environment variables between Infinite Scale version 7.3.0 and 8.0.0. +:description: This page contains tables with added and removed environment variables between Infinite Scale version 8.1.0 and 8.2.0. :page-aliases: ROOT:deployment/services/env-var-changes.adoc -:source_path: {ocis_services_raw_url}{service_url_component}{ocis_services_env_var_deltas_path} - //// to be set in antora.yml -ocis_services_raw_url: https://raw.githubusercontent.com/owncloud/ocis/ -service_url_component: docs || docs-stable-8.0 -ocis_services_env_var_deltas_path: /services/general-info/envvars/env-var-deltas/ -env_var_delta_name: 7.3.0-8.0.0 +ocis_helpers: example$ocis_helpers +ocis_helpers_env_var_deltas: {ocis_helpers}/env_var_deltas/ +env_var_delta_name: 8.3.0-8.2.0 //// == Introduction @@ -25,16 +22,16 @@ env_var_delta_name: 7.3.0-8.0.0 Added:: + -- -include::{source_path}{env_var_delta_name}-added.adoc[] +include::example${ocis_helpers_env_var_deltas}{env_var_delta_name}-added.adoc[] -- Removed:: + -- -include::{source_path}{env_var_delta_name}-removed.adoc[] +include::example${ocis_helpers_env_var_deltas}{env_var_delta_name}-removed.adoc[] -- Deprecated:: + -- -include::{source_path}{env_var_delta_name}-deprecated.adoc[] +include::example${ocis_helpers_env_var_deltas}{env_var_delta_name}-deprecated.adoc[] -- ==== diff --git a/content/ocis/8.2/modules/admin/pages/deployment/services/env-vars-special-scope.adoc b/content/ocis/8.2/modules/admin/pages/deployment/services/env-vars-special-scope.adoc index 2fef2fd..5ac231b 100644 --- a/content/ocis/8.2/modules/admin/pages/deployment/services/env-vars-special-scope.adoc +++ b/content/ocis/8.2/modules/admin/pages/deployment/services/env-vars-special-scope.adoc @@ -13,7 +13,6 @@ Examples: * The extended environment variable `OCIS_CONFIG_DIR` can be used with `ocis init`. * The special environment variable `OCIS_RUN_SERVICES` defines services to start when the container is started. - == Special Environment Variables // these envvars cant be gathered automatically and must be maintained manually. they change very rarely! @@ -24,23 +23,20 @@ The following environment variables are only available when using a developer ve include::partial$deployment/services/env-and-yaml.adoc[tag=special_envvars] - == Extended Environment Variables //// -IMPORTANT: extended envvars currently do not have an extended_deprecation.adoc file. handled in the include. +IMPORTANT: extended envvars currently do not have an extended_deprecation.adoc file. this is handled in the include. -note that if a description of an extended envvar missing or strange looking envvars present, you need to fix this in: -https://github.com/owncloud/ocis/blob/master/docs/helpers/extended_vars.yaml -see the readme.md file in that folder. +note that if a description of an extended envvar missing or strange looking envvars present, +you need to fix this via the ocis_helper executable in this repo. see the readme of the helper for details. //// :service_name: extended Note, see the xref:deployment/services/registry.adoc[Registry] documentation for details on the Micro Registry and their available settings. -include::partial$deployment/services/env-and-yaml.adoc[tag=envvars-only] - +include::partial$deployment/services/env-and-yaml.adoc[tag=extended-only] == Global Environment Variables @@ -50,4 +46,4 @@ include::partial$deployment/services/env-and-yaml.adoc[tag=envvars-only] Note that the descriptions of these environment variables may differ depending on the service context. -include::partial$deployment/services/env-and-yaml.adoc[tag=envvars-only] +include::partial$deployment/services/env-and-yaml.adoc[tag=global-only] diff --git a/content/ocis/8.2/modules/admin/pages/deployment/services/s-list/policies.adoc b/content/ocis/8.2/modules/admin/pages/deployment/services/s-list/policies.adoc index 5b836aa..3b2a1fc 100644 --- a/content/ocis/8.2/modules/admin/pages/deployment/services/s-list/policies.adoc +++ b/content/ocis/8.2/modules/admin/pages/deployment/services/s-list/policies.adoc @@ -164,12 +164,12 @@ The policies service contains a set of preconfigured example policies. See the d [tabs] ==== -{service_tab_text}:: +{tab_text}:: + -- {compose_url}{compose_version}{compose_final_path}[Rego policies deployment example directory,window=_blank] -Using git branch name: `{compose_version}`, to point to the latest stable version that also includes patches +Using git branch name: `{compose_version}`, to point to the latest stable version that also includes patches. -- ==== diff --git a/content/ocis/8.2/modules/admin/pages/deployment/webui/webui-theming.adoc b/content/ocis/8.2/modules/admin/pages/deployment/webui/webui-theming.adoc index 14c581c..e320750 100644 --- a/content/ocis/8.2/modules/admin/pages/deployment/webui/webui-theming.adoc +++ b/content/ocis/8.2/modules/admin/pages/deployment/webui/webui-theming.adoc @@ -42,7 +42,12 @@ Some theme keys are mandatory, like the `common.shareRoles` settings. Such manda == Configuring a Theme -.Sourced from https://github.com/owncloud/ocis/blob/{compose_version}{web_assets_path}theme.json[GitHub, _window=blank] +:configuring_add_on_text: +ifdef::page-component-version-is-prerelease[] +:configuring_add_on_text: from the latest stable version. +endif::[] + +.Sourced from https://github.com/owncloud/ocis/blob/{compose_version}{web_assets_path}theme.json[GitHub, _window=blank] {configuring_add_on_text} [source,json] ---- include::{ocis_services_raw_url}{compose_version}{web_assets_path}theme.json[] diff --git a/content/ocis/8.2/modules/admin/pages/deployment/wopi/wopi.adoc b/content/ocis/8.2/modules/admin/pages/deployment/wopi/wopi.adoc index db2fe47..c8fd68f 100644 --- a/content/ocis/8.2/modules/admin/pages/deployment/wopi/wopi.adoc +++ b/content/ocis/8.2/modules/admin/pages/deployment/wopi/wopi.adoc @@ -73,7 +73,7 @@ image::deployment/wopi/wopi-overview.svg[WOPI Overview Diagram,width=500] + [tabs] ==== -{service_tab_text}:: +{tab_text}:: + -- {compose_url}{compose_version}{compose_final_path}/{ocis_wopi}[Docker compose `ocis_full` deployment example directory,window=_blank] diff --git a/content/ocis/8.2/modules/admin/pages/index.adoc b/content/ocis/8.2/modules/admin/pages/index.adoc index 4c5309c..3ef114e 100644 --- a/content/ocis/8.2/modules/admin/pages/index.adoc +++ b/content/ocis/8.2/modules/admin/pages/index.adoc @@ -71,4 +71,4 @@ Configuration of Infinite Scale might be quite different to what you are used to == End-User License Agreement (EULA) -ownCloud provides an EULA to clarify, among various topics, who can use this software and which conditions apply to the groups of users defined. See the actual {compose_raw_url}{compose_version}/assets/End-User-License-Agreement-for-ownCloud-Infinite-Scale.pdf[EULA] for details. +ownCloud provides an EULA to clarify, among various topics, who can use this software and which conditions apply to the groups of users defined. See the actual {compose_raw_url}{ocis_git_version}/assets/End-User-License-Agreement-for-ownCloud-Infinite-Scale.pdf[EULA] for details. diff --git a/content/ocis/8.2/modules/admin/partials/depl-examples/ubuntu-compose/shared-setup.adoc b/content/ocis/8.2/modules/admin/partials/depl-examples/ubuntu-compose/shared-setup.adoc index 3f8b11a..87c004b 100644 --- a/content/ocis/8.2/modules/admin/partials/depl-examples/ubuntu-compose/shared-setup.adoc +++ b/content/ocis/8.2/modules/admin/partials/depl-examples/ubuntu-compose/shared-setup.adoc @@ -250,7 +250,14 @@ NOTE: The client that downloads the example is not the server that you upload to NOTE: The client from which you download the example via a browser and upload it using `scp` must have access to the server and have the `scp` application installed. -To download and extract the necessary deployment example footnote:[Derived from the {compose_url}{compose_version}{compose_final_path}/{ocis_wopi}/[{ocis_wopi}, window=_blank] developer example], *open a browser* and enter the following URL. Note that this link also contains patches for release: `{ocis-actual-version}`. +:note_text: +ifdef::page-component-version-is-prerelease[] +:note_text: There is no download for the ocis development version for stability reasons. The latest stable release {page-component-latest-version} is used instead. +endif::[] + +{note_text} + +To download and extract the necessary deployment example footnote:[Derived from the {compose_url}{compose_version}{compose_final_path}/{ocis_wopi}/[{ocis_wopi}, window=_blank] developer example], *open a browser* and enter the following URL. Note that this link also contains patches, if any, for the stable release branch: `{compose_version}`. //[source,url,subs="attributes+,+macros"] //---- @@ -329,7 +336,7 @@ Add a valid response eMail address for Letsencrypt, see the note below. Set the CAServer to staging, see the note below. * `OCIS_DOCKER_IMAGE` + -Check that the correct image type is selected ({version-type}). +Check that the correct image type is selected. * `OCIS_DOMAIN`, `COLLABORA_DOMAIN` and/or `ONLYOFFICE_DOMAIN` + Set the domain names as defined in xref:domain-names[Domain Names]. @@ -649,14 +656,10 @@ docker volume rm {ocis_wopi}_ocis-config {ocis_wopi}_ocis-data === Updating -// for testing only -//:version-type: rolling -//:version-type: production - Infinite Scale:: + -- -ifeval::["{version-type}" == "rolling"] +ifdef::page-component-version-is-prerelease[] For Infinite Scale rolling releases, the following steps are essential to avoid breaking the setup. This is because rolling releases depend on all updates being done in sequence. When new versions of Infinite Scale are available, you *may* skip any version between the one you are currently running and the latest available rolling release for internal update reasons. All versions must be downloaded and launched at once. For more details, see https://owncloud.dev/ocis/release_roadmap/#updating-and-overlap[Updating and Overlap] in the developer documentation. @@ -682,7 +685,7 @@ Note that we recommend manually checking to see if the deployment source has cha endif::[] -ifeval::["{version-type}" != "rolling"] +ifndef::page-component-version-is-prerelease[] Follow these steps to update between production releases: diff --git a/content/ocis/8.2/modules/admin/partials/deployment/services/env-and-yaml.adoc b/content/ocis/8.2/modules/admin/partials/deployment/services/env-and-yaml.adoc index b0f093d..f1c214a 100644 --- a/content/ocis/8.2/modules/admin/partials/deployment/services/env-and-yaml.adoc +++ b/content/ocis/8.2/modules/admin/partials/deployment/services/env-and-yaml.adoc @@ -15,7 +15,7 @@ Important: The xxx_deprecation.adoc does not exist for extended or global envvar tag::special_envvars[] // compute the correct tab text -include::partial$multi-location/tab-text.adoc[] +include::partial$multi-location/compose-version.adoc[] // this directive is usually not necessary and its need likely an antora bug. because there is no text after the include // and the tabs, we need to simulate this with empty. using it we prevent a warning that the attribute is missing... @@ -23,7 +23,7 @@ include::partial$multi-location/tab-text.adoc[] [tabs] ==== -{tab_text}:: +{env_tab_text}:: + -- [caption=] @@ -62,22 +62,22 @@ end::special_envvars[] tag::envvars-yaml[] // compute the correct tab text -include::partial$multi-location/tab-text.adoc[] +include::partial$multi-location/compose-version.adoc[] === Environment Variables The `{service_name}` service is configured via the following environment variables. Read the xref:deployment/services/envvar-types-description.adoc[Environment Variable Types] documentation for important details. Column `IV` shows with which release the environment variable has been introduced. // load the deprecation activation file. this will overwrite the above. -include::{ocis_services_raw_url}{service_url_component}{ocis_services_final_path}adoc/{service_name}_deprecation.adoc[] +include::example${ocis_helpers_adoc}{service_name}_deprecation.adoc[] [tabs] ==== -{tab_text}:: +{env_tab_text}:: + -- // if deprecation activation is true, it will also show the deprecation content. -include::{ocis_services_raw_url}{service_url_component}{ocis_services_final_path}adoc/{service_name}_configvars.adoc[] +include::example${ocis_helpers_adoc}{service_name}_configvars.adoc[] -- ==== @@ -88,12 +88,12 @@ include::{ocis_services_raw_url}{service_url_component}{ocis_services_final_path [tabs] ==== -{tab_text}:: +{env_tab_text}:: + -- [source,yaml] ---- -include::{ocis_services_raw_url}{service_url_component}{ocis_services_final_path}{service_name}-config-example.yaml[] +include::example${ocis_helpers_yaml}{service_name}-config-example.yaml[] ---- -- ==== @@ -101,16 +101,43 @@ include::{ocis_services_raw_url}{service_url_component}{ocis_services_final_path end::envvars-yaml[] +// TEXT VERSION 2 only print global envvars (no yaml available) -// TEXT VERSION 2 only print envvars +tag::global-only[] -tag::envvars-only[] +// default to not show deprecations +:show-deprecation: false + +// compute the correct tab text +include::partial$multi-location/compose-version.adoc[] + +The `{service_name}` variables are defined in the following way. Read the xref:deployment/services/envvar-types-description.adoc[Environment Variable Types] documentation for important details. Column `IV` shows with which release the environment variable has been introduced. + +// do not load any deprecation activations. use the default set via ':show-deprecation: false' above +// this prevents showing any deprecations which is necessary for global envvars which currently do not have +// any deprecations configured. + +[tabs] +==== +{env_tab_text}:: ++ +-- +include::example${ocis_helpers_adoc}{service_name}_configvars.adoc[] +-- +==== + +end::global-only[] + + +// TEXT VERSION 3 only print extended envvars (no yaml available) + +tag::extended-only[] // default to not show deprecations :show-deprecation: false // compute the correct tab text -include::partial$multi-location/tab-text.adoc[] +include::partial$multi-location/compose-version.adoc[] The `{service_name}` variables are defined in the following way. Read the xref:deployment/services/envvar-types-description.adoc[Environment Variable Types] documentation for important details. Column `IV` shows with which release the environment variable has been introduced. @@ -120,11 +147,11 @@ The `{service_name}` variables are defined in the following way. Read the xref:d [tabs] ==== -{tab_text}:: +{env_tab_text}:: + -- -include::{ocis_services_raw_url}{service_url_component}{ocis_services_final_path}adoc/{service_name}_configvars.adoc[] +include::example${ocis_helpers_extended}{service_name}_configvars.adoc[] -- ==== -end::envvars-only[] +end::extended-only[] diff --git a/content/ocis/8.2/modules/admin/partials/multi-location/compose-version.adoc b/content/ocis/8.2/modules/admin/partials/multi-location/compose-version.adoc index 81006a4..9a37a68 100644 --- a/content/ocis/8.2/modules/admin/partials/multi-location/compose-version.adoc +++ b/content/ocis/8.2/modules/admin/partials/multi-location/compose-version.adoc @@ -1,28 +1,25 @@ //// -depending of the version (production/rolling), attributes get defined dynamically +depending of the version (stable/development), attributes get defined dynamically -if the branch is master, identified via the component version equals 'next', we have a rolling release -if the branch is anything else, it is a production version and has its own branch +if the branch is master, identified via attribute page-component-version-is-prerelease, we must point to the latest stable +if the branch is anything else, it is a stable version and and can be used as is (stable-x.y) -the outcome guarantees that we always access the correct paths to get or reference source files from - -ocis_repo_url_component: defined in antora.yml: is either master or a branched version -ocis_repo_url_stable: defined in antora.yml: is always the latest stable branch of this version -antora-component-version: intrinsic via antora.yml: is either next or a branched version like 7.2 +the outcome guarantees that we always access the correct paths to get or reference to source files from //// -// first we define the default -// production (because it has an own doc branch) -// url is either master or like stable-7.2 -:compose_version: {ocis_repo_url_component} -:version-type: production +// first we define the default which is stable +// url assembled points to any valid stable-x.y +:compose_version: stable-{page-component-version} +:tab_text: {page-component-version} +:env_tab_text: {page-component-version} +:ocis_git_version: stable-{page-component-version} // but: -// if it is the master branch, defined as next, we need to redefine to a stable branch +// if it is the prerelease (master branch == development), we need to redefine to the latest stable branch // master may contain non functional data -// latest-ocis-version is defined in global-attributes.yml: 7.2 or 7.1 -// the file is included via an extension -ifeval::["{antora-component-version}" == "next"] -:compose_version: {ocis_repo_url_stable} -:version-type: rolling +ifdef::page-component-version-is-prerelease[] +:compose_version: stable-{page-component-latest-version} +:tab_text: {page-component-latest-version} +:env_tab_text: master +:ocis_git_version: master endif::[] diff --git a/content/ocis/8.2/modules/admin/partials/multi-location/tab-text.adoc b/content/ocis/8.2/modules/admin/partials/multi-location/tab-text.adoc deleted file mode 100644 index 3317e57..0000000 --- a/content/ocis/8.2/modules/admin/partials/multi-location/tab-text.adoc +++ /dev/null @@ -1,12 +0,0 @@ -//// -the tab text printed depends on if you are on master, then it is 'master + Rolling ' -or it is the value of the name as defined in antora.yml -//// - -// compute the correct tab text -:tab_text: {service_tab_text} - -// we do not make rolling releases anymore, keeping the code if that changes -// ifeval::["{service_tab_text}" == "master"] -// :tab_text: {service_tab_text} + Rolling {ocis-rolling-version} -// endif::[] diff --git a/content/ocis/8.3/antora.yml b/content/ocis/8.3/antora.yml index ff74043..8ed07db 100644 --- a/content/ocis/8.3/antora.yml +++ b/content/ocis/8.3/antora.yml @@ -9,45 +9,19 @@ nav: asciidoc: attributes: - # with antora 3.2, there will be new attributes `antora-component-version` and `antora-component-name` - # the ones used below need to be replaced when antora has been updated to 3.2 - # https://gitlab.com/antora/antora/-/merge_requests/1048/diffs - latest-ocis-version: {page-component-version} # do not change, this is the value of the version key - previous-ocis-version: {page-component-version} # do not change, this is the value of the version key - - # must be removed when antora 3.2 has been updated, because this is then an intrinsic attribute - # the branched value is the value for the production release like 'next' or '7.1' - antora-component-version: '8.3' - # used to define the include path for services without trailing / # note that any changes of this path also need adjustment in # https://github.com/owncloud/ocis-charts/tree/master/charts/ocis/docs s-path: 'deployment/services/s-list' # the name of the sub directory that defines the sources folder used in the compose deployment examples - ocis_wopi: ocis_full - - # note that service_url_component is used for services ONLY - # service_url_component will be used to assemble the url for services to include content (tables) - # sourced from the ocis repo. - # 'docs' for the next branch or 'docs-stable-7.2' for a production branch - service_url_component: 'docs' - - # defines the url path component when accessing the ocis repo for versioned data includes or examples - # 'master' for the next branch or 'stable-7.2' for a production branch - # example: {compose_url}{ocis_repo_url_component}{compose_final_path} - ocis_repo_url_component: 'master' - - # this always points to the latest stable branch such as 'stable-7.2' - # this branch also includes patches if any - # used for links where you would else download from master but the content better comes from stable - ocis_repo_url_stable: 'stable-8.2' + ocis_wopi: 'ocis_full' - # service_tab_text will be used as tab text shown for the tables in services only - # note when literally changing the word 'master' to something else, you also must adapt 'env-and-yaml.adoc'. - # this does not apply to branched releases using semver, only to the master branch! - # 'master' for the next branch or '7.2.0' for a production branch including patch releases like `7.2.1' - service_tab_text: 'master' + ocis_helpers: 'ocis_helpers' # note the preceding 'example$' (family coordinate) cant be used as part of the attribute + ocis_helpers_adoc: '{ocis_helpers}/adoc/' + ocis_helpers_env_var_deltas: '{ocis_helpers}/env_var_deltas/' + ocis_helpers_extended: '{ocis_helpers}/extended/' + ocis_helpers_yaml: '{ocis_helpers}/yaml/' # this is the first part of the name for envvars between major versions that will be added or removed # example for full name: 7.0.0-7.1.0-added.adoc or 7.0.0-7.1.0-removed.adoc @@ -56,21 +30,20 @@ asciidoc: # set attributes defining path components which will be assembled in the document compose_url: 'https://github.com/owncloud/ocis/tree/' - compose_raw_url: 'https://raw.githubusercontent.com/owncloud/ocis/' + compose_raw_url: 'https://raw.githubusercontent.com/owncloud/ocis/refs/heads/' compose_final_path: '/deployments/examples' - # production and rolling have separate paths when it comes to download from docker - docker_ocis_prod_url: https://hub.docker.com/r/owncloud/ocis - docker_ocis_rolling_url: https://hub.docker.com/r/owncloud/ocis-rolling - # only used in deployment/services via partials/env-and-yaml.adoc # static path components, used to assemble the final path dependent on service_url_component to include services - ocis_services_raw_url: 'https://raw.githubusercontent.com/owncloud/ocis/' - ocis_services_final_path: '/services/_includes/' + ocis_services_raw_url: 'https://raw.githubusercontent.com/owncloud/ocis/refs/heads/' - # only used in deployment/services/env-var-changes.adoc - # static path component, used to assemble the final path - ocis_services_env_var_deltas_path: '/services/general-info/envvars/env-var-deltas/' + # production and rolling have separate paths when it comes to download from docker + docker_ocis_prod_url: 'https://hub.docker.com/r/owncloud/ocis' + docker_ocis_rolling_url: 'https://hub.docker.com/r/owncloud/ocis-rolling' # used in depl-examples - download-gh-directory-url: https://download-directory.github.io + download-gh-directory-url: 'https://download-directory.github.io' + + # the url to download ocis + # note that this is inactive but required in the migration section for upgrading old binaries which do not longer exist. + ocis-downloadpage-url: 'https://download.owncloud.com/ocis/ocis' diff --git a/content/ocis/8.3/modules/admin/pages/depl-examples/ubuntu-compose/ubuntu-compose-hetzner.adoc b/content/ocis/8.3/modules/admin/pages/depl-examples/ubuntu-compose/ubuntu-compose-hetzner.adoc index 02c7b39..a68b24f 100644 --- a/content/ocis/8.3/modules/admin/pages/depl-examples/ubuntu-compose/ubuntu-compose-hetzner.adoc +++ b/content/ocis/8.3/modules/admin/pages/depl-examples/ubuntu-compose/ubuntu-compose-hetzner.adoc @@ -23,7 +23,7 @@ IMPORTANT: By choosing https://www.hetzner.com[Hetzner] for our cloud deployment NOTE: With the minimum configuration available on Hetzner, you can start with about €4/month for a cloud driven Infinite Scale deployment. Note that prices are subject to changes and only intended for informational purposes. -NOTE: This guide references the latest {version-type} version of Infinite Scale. +NOTE: This guide references the latest stable version of Infinite Scale. NOTE: With this setup, each deployment only contains one instance of Infinite Scale. diff --git a/content/ocis/8.3/modules/admin/pages/depl-examples/ubuntu-compose/ubuntu-compose-prod.adoc b/content/ocis/8.3/modules/admin/pages/depl-examples/ubuntu-compose/ubuntu-compose-prod.adoc index 8e53c66..4a5ce55 100644 --- a/content/ocis/8.3/modules/admin/pages/depl-examples/ubuntu-compose/ubuntu-compose-prod.adoc +++ b/content/ocis/8.3/modules/admin/pages/depl-examples/ubuntu-compose/ubuntu-compose-prod.adoc @@ -25,7 +25,7 @@ toc::[] IMPORTANT: *There are several decisions and steps that need to be taken when setting up and configuring the server. We strongly recommend that you read the manual and not just try to copy and paste commands.* -NOTE: This guide references the latest {version-type} version of Infinite Scale. +NOTE: This guide references the latest stable version of Infinite Scale. NOTE: With this setup, each deployment only contains one instance of Infinite Scale. diff --git a/content/ocis/8.3/modules/admin/pages/deployment/general/general-info.adoc b/content/ocis/8.3/modules/admin/pages/deployment/general/general-info.adoc index 4a0a4c0..bf5e846 100644 --- a/content/ocis/8.3/modules/admin/pages/deployment/general/general-info.adoc +++ b/content/ocis/8.3/modules/admin/pages/deployment/general/general-info.adoc @@ -630,7 +630,7 @@ This is the local path the where Infinite Scale stores all data except the confi This is the local path where the Infinite Scale configuration is stored. When listing the content, you must see the file `ocis.yaml`. See the important information when using xref:docker-volumes[Docker Volumes]. * `` + -The Infinite Scale version used like `latest` or `{ocis-actual-version}` or ... . +The Infinite Scale version used like `latest` or `{page-component-latest-version}` or ... . + -- [source,bash] diff --git a/content/ocis/8.3/modules/admin/pages/deployment/services/env-var-changes.adoc b/content/ocis/8.3/modules/admin/pages/deployment/services/env-var-changes.adoc index ed8ce2a..e4f5136 100644 --- a/content/ocis/8.3/modules/admin/pages/deployment/services/env-var-changes.adoc +++ b/content/ocis/8.3/modules/admin/pages/deployment/services/env-var-changes.adoc @@ -1,17 +1,14 @@ # Changed Environment Variables in Versions :toc: right -:description: This page contains tables with added and removed environment variables between Infinite Scale version 7.3.0 and 8.0.0. +:description: This page contains tables with added and removed environment variables between Infinite Scale version 8.2.0 and 8.3.0. :page-aliases: ROOT:deployment/services/env-var-changes.adoc -:source_path: {ocis_services_raw_url}{service_url_component}{ocis_services_env_var_deltas_path} - //// to be set in antora.yml -ocis_services_raw_url: https://raw.githubusercontent.com/owncloud/ocis/ -service_url_component: docs || docs-stable-8.0 -ocis_services_env_var_deltas_path: /services/general-info/envvars/env-var-deltas/ -env_var_delta_name: 7.3.0-8.0.0 +ocis_helpers: example$ocis_helpers +ocis_helpers_env_var_deltas: {ocis_helpers}/env_var_deltas/ +env_var_delta_name: 8.3.0-8.2.0 //// == Introduction @@ -25,16 +22,16 @@ env_var_delta_name: 7.3.0-8.0.0 Added:: + -- -include::{source_path}{env_var_delta_name}-added.adoc[] +include::example${ocis_helpers_env_var_deltas}{env_var_delta_name}-added.adoc[] -- Removed:: + -- -include::{source_path}{env_var_delta_name}-removed.adoc[] +include::example${ocis_helpers_env_var_deltas}{env_var_delta_name}-removed.adoc[] -- Deprecated:: + -- -include::{source_path}{env_var_delta_name}-deprecated.adoc[] +include::example${ocis_helpers_env_var_deltas}{env_var_delta_name}-deprecated.adoc[] -- ==== diff --git a/content/ocis/8.3/modules/admin/pages/deployment/services/env-vars-special-scope.adoc b/content/ocis/8.3/modules/admin/pages/deployment/services/env-vars-special-scope.adoc index 2fef2fd..5ac231b 100644 --- a/content/ocis/8.3/modules/admin/pages/deployment/services/env-vars-special-scope.adoc +++ b/content/ocis/8.3/modules/admin/pages/deployment/services/env-vars-special-scope.adoc @@ -13,7 +13,6 @@ Examples: * The extended environment variable `OCIS_CONFIG_DIR` can be used with `ocis init`. * The special environment variable `OCIS_RUN_SERVICES` defines services to start when the container is started. - == Special Environment Variables // these envvars cant be gathered automatically and must be maintained manually. they change very rarely! @@ -24,23 +23,20 @@ The following environment variables are only available when using a developer ve include::partial$deployment/services/env-and-yaml.adoc[tag=special_envvars] - == Extended Environment Variables //// -IMPORTANT: extended envvars currently do not have an extended_deprecation.adoc file. handled in the include. +IMPORTANT: extended envvars currently do not have an extended_deprecation.adoc file. this is handled in the include. -note that if a description of an extended envvar missing or strange looking envvars present, you need to fix this in: -https://github.com/owncloud/ocis/blob/master/docs/helpers/extended_vars.yaml -see the readme.md file in that folder. +note that if a description of an extended envvar missing or strange looking envvars present, +you need to fix this via the ocis_helper executable in this repo. see the readme of the helper for details. //// :service_name: extended Note, see the xref:deployment/services/registry.adoc[Registry] documentation for details on the Micro Registry and their available settings. -include::partial$deployment/services/env-and-yaml.adoc[tag=envvars-only] - +include::partial$deployment/services/env-and-yaml.adoc[tag=extended-only] == Global Environment Variables @@ -50,4 +46,4 @@ include::partial$deployment/services/env-and-yaml.adoc[tag=envvars-only] Note that the descriptions of these environment variables may differ depending on the service context. -include::partial$deployment/services/env-and-yaml.adoc[tag=envvars-only] +include::partial$deployment/services/env-and-yaml.adoc[tag=global-only] diff --git a/content/ocis/8.3/modules/admin/pages/deployment/services/s-list/policies.adoc b/content/ocis/8.3/modules/admin/pages/deployment/services/s-list/policies.adoc index 5b836aa..3b2a1fc 100644 --- a/content/ocis/8.3/modules/admin/pages/deployment/services/s-list/policies.adoc +++ b/content/ocis/8.3/modules/admin/pages/deployment/services/s-list/policies.adoc @@ -164,12 +164,12 @@ The policies service contains a set of preconfigured example policies. See the d [tabs] ==== -{service_tab_text}:: +{tab_text}:: + -- {compose_url}{compose_version}{compose_final_path}[Rego policies deployment example directory,window=_blank] -Using git branch name: `{compose_version}`, to point to the latest stable version that also includes patches +Using git branch name: `{compose_version}`, to point to the latest stable version that also includes patches. -- ==== diff --git a/content/ocis/8.3/modules/admin/pages/deployment/webui/webui-theming.adoc b/content/ocis/8.3/modules/admin/pages/deployment/webui/webui-theming.adoc index 14c581c..e320750 100644 --- a/content/ocis/8.3/modules/admin/pages/deployment/webui/webui-theming.adoc +++ b/content/ocis/8.3/modules/admin/pages/deployment/webui/webui-theming.adoc @@ -42,7 +42,12 @@ Some theme keys are mandatory, like the `common.shareRoles` settings. Such manda == Configuring a Theme -.Sourced from https://github.com/owncloud/ocis/blob/{compose_version}{web_assets_path}theme.json[GitHub, _window=blank] +:configuring_add_on_text: +ifdef::page-component-version-is-prerelease[] +:configuring_add_on_text: from the latest stable version. +endif::[] + +.Sourced from https://github.com/owncloud/ocis/blob/{compose_version}{web_assets_path}theme.json[GitHub, _window=blank] {configuring_add_on_text} [source,json] ---- include::{ocis_services_raw_url}{compose_version}{web_assets_path}theme.json[] diff --git a/content/ocis/8.3/modules/admin/pages/deployment/wopi/wopi.adoc b/content/ocis/8.3/modules/admin/pages/deployment/wopi/wopi.adoc index db2fe47..c8fd68f 100644 --- a/content/ocis/8.3/modules/admin/pages/deployment/wopi/wopi.adoc +++ b/content/ocis/8.3/modules/admin/pages/deployment/wopi/wopi.adoc @@ -73,7 +73,7 @@ image::deployment/wopi/wopi-overview.svg[WOPI Overview Diagram,width=500] + [tabs] ==== -{service_tab_text}:: +{tab_text}:: + -- {compose_url}{compose_version}{compose_final_path}/{ocis_wopi}[Docker compose `ocis_full` deployment example directory,window=_blank] diff --git a/content/ocis/8.3/modules/admin/pages/index.adoc b/content/ocis/8.3/modules/admin/pages/index.adoc index 4c5309c..3ef114e 100644 --- a/content/ocis/8.3/modules/admin/pages/index.adoc +++ b/content/ocis/8.3/modules/admin/pages/index.adoc @@ -71,4 +71,4 @@ Configuration of Infinite Scale might be quite different to what you are used to == End-User License Agreement (EULA) -ownCloud provides an EULA to clarify, among various topics, who can use this software and which conditions apply to the groups of users defined. See the actual {compose_raw_url}{compose_version}/assets/End-User-License-Agreement-for-ownCloud-Infinite-Scale.pdf[EULA] for details. +ownCloud provides an EULA to clarify, among various topics, who can use this software and which conditions apply to the groups of users defined. See the actual {compose_raw_url}{ocis_git_version}/assets/End-User-License-Agreement-for-ownCloud-Infinite-Scale.pdf[EULA] for details. diff --git a/content/ocis/8.3/modules/admin/partials/depl-examples/ubuntu-compose/shared-setup.adoc b/content/ocis/8.3/modules/admin/partials/depl-examples/ubuntu-compose/shared-setup.adoc index 3f8b11a..87c004b 100644 --- a/content/ocis/8.3/modules/admin/partials/depl-examples/ubuntu-compose/shared-setup.adoc +++ b/content/ocis/8.3/modules/admin/partials/depl-examples/ubuntu-compose/shared-setup.adoc @@ -250,7 +250,14 @@ NOTE: The client that downloads the example is not the server that you upload to NOTE: The client from which you download the example via a browser and upload it using `scp` must have access to the server and have the `scp` application installed. -To download and extract the necessary deployment example footnote:[Derived from the {compose_url}{compose_version}{compose_final_path}/{ocis_wopi}/[{ocis_wopi}, window=_blank] developer example], *open a browser* and enter the following URL. Note that this link also contains patches for release: `{ocis-actual-version}`. +:note_text: +ifdef::page-component-version-is-prerelease[] +:note_text: There is no download for the ocis development version for stability reasons. The latest stable release {page-component-latest-version} is used instead. +endif::[] + +{note_text} + +To download and extract the necessary deployment example footnote:[Derived from the {compose_url}{compose_version}{compose_final_path}/{ocis_wopi}/[{ocis_wopi}, window=_blank] developer example], *open a browser* and enter the following URL. Note that this link also contains patches, if any, for the stable release branch: `{compose_version}`. //[source,url,subs="attributes+,+macros"] //---- @@ -329,7 +336,7 @@ Add a valid response eMail address for Letsencrypt, see the note below. Set the CAServer to staging, see the note below. * `OCIS_DOCKER_IMAGE` + -Check that the correct image type is selected ({version-type}). +Check that the correct image type is selected. * `OCIS_DOMAIN`, `COLLABORA_DOMAIN` and/or `ONLYOFFICE_DOMAIN` + Set the domain names as defined in xref:domain-names[Domain Names]. @@ -649,14 +656,10 @@ docker volume rm {ocis_wopi}_ocis-config {ocis_wopi}_ocis-data === Updating -// for testing only -//:version-type: rolling -//:version-type: production - Infinite Scale:: + -- -ifeval::["{version-type}" == "rolling"] +ifdef::page-component-version-is-prerelease[] For Infinite Scale rolling releases, the following steps are essential to avoid breaking the setup. This is because rolling releases depend on all updates being done in sequence. When new versions of Infinite Scale are available, you *may* skip any version between the one you are currently running and the latest available rolling release for internal update reasons. All versions must be downloaded and launched at once. For more details, see https://owncloud.dev/ocis/release_roadmap/#updating-and-overlap[Updating and Overlap] in the developer documentation. @@ -682,7 +685,7 @@ Note that we recommend manually checking to see if the deployment source has cha endif::[] -ifeval::["{version-type}" != "rolling"] +ifndef::page-component-version-is-prerelease[] Follow these steps to update between production releases: diff --git a/content/ocis/8.3/modules/admin/partials/deployment/services/env-and-yaml.adoc b/content/ocis/8.3/modules/admin/partials/deployment/services/env-and-yaml.adoc index b0f093d..f1c214a 100644 --- a/content/ocis/8.3/modules/admin/partials/deployment/services/env-and-yaml.adoc +++ b/content/ocis/8.3/modules/admin/partials/deployment/services/env-and-yaml.adoc @@ -15,7 +15,7 @@ Important: The xxx_deprecation.adoc does not exist for extended or global envvar tag::special_envvars[] // compute the correct tab text -include::partial$multi-location/tab-text.adoc[] +include::partial$multi-location/compose-version.adoc[] // this directive is usually not necessary and its need likely an antora bug. because there is no text after the include // and the tabs, we need to simulate this with empty. using it we prevent a warning that the attribute is missing... @@ -23,7 +23,7 @@ include::partial$multi-location/tab-text.adoc[] [tabs] ==== -{tab_text}:: +{env_tab_text}:: + -- [caption=] @@ -62,22 +62,22 @@ end::special_envvars[] tag::envvars-yaml[] // compute the correct tab text -include::partial$multi-location/tab-text.adoc[] +include::partial$multi-location/compose-version.adoc[] === Environment Variables The `{service_name}` service is configured via the following environment variables. Read the xref:deployment/services/envvar-types-description.adoc[Environment Variable Types] documentation for important details. Column `IV` shows with which release the environment variable has been introduced. // load the deprecation activation file. this will overwrite the above. -include::{ocis_services_raw_url}{service_url_component}{ocis_services_final_path}adoc/{service_name}_deprecation.adoc[] +include::example${ocis_helpers_adoc}{service_name}_deprecation.adoc[] [tabs] ==== -{tab_text}:: +{env_tab_text}:: + -- // if deprecation activation is true, it will also show the deprecation content. -include::{ocis_services_raw_url}{service_url_component}{ocis_services_final_path}adoc/{service_name}_configvars.adoc[] +include::example${ocis_helpers_adoc}{service_name}_configvars.adoc[] -- ==== @@ -88,12 +88,12 @@ include::{ocis_services_raw_url}{service_url_component}{ocis_services_final_path [tabs] ==== -{tab_text}:: +{env_tab_text}:: + -- [source,yaml] ---- -include::{ocis_services_raw_url}{service_url_component}{ocis_services_final_path}{service_name}-config-example.yaml[] +include::example${ocis_helpers_yaml}{service_name}-config-example.yaml[] ---- -- ==== @@ -101,16 +101,43 @@ include::{ocis_services_raw_url}{service_url_component}{ocis_services_final_path end::envvars-yaml[] +// TEXT VERSION 2 only print global envvars (no yaml available) -// TEXT VERSION 2 only print envvars +tag::global-only[] -tag::envvars-only[] +// default to not show deprecations +:show-deprecation: false + +// compute the correct tab text +include::partial$multi-location/compose-version.adoc[] + +The `{service_name}` variables are defined in the following way. Read the xref:deployment/services/envvar-types-description.adoc[Environment Variable Types] documentation for important details. Column `IV` shows with which release the environment variable has been introduced. + +// do not load any deprecation activations. use the default set via ':show-deprecation: false' above +// this prevents showing any deprecations which is necessary for global envvars which currently do not have +// any deprecations configured. + +[tabs] +==== +{env_tab_text}:: ++ +-- +include::example${ocis_helpers_adoc}{service_name}_configvars.adoc[] +-- +==== + +end::global-only[] + + +// TEXT VERSION 3 only print extended envvars (no yaml available) + +tag::extended-only[] // default to not show deprecations :show-deprecation: false // compute the correct tab text -include::partial$multi-location/tab-text.adoc[] +include::partial$multi-location/compose-version.adoc[] The `{service_name}` variables are defined in the following way. Read the xref:deployment/services/envvar-types-description.adoc[Environment Variable Types] documentation for important details. Column `IV` shows with which release the environment variable has been introduced. @@ -120,11 +147,11 @@ The `{service_name}` variables are defined in the following way. Read the xref:d [tabs] ==== -{tab_text}:: +{env_tab_text}:: + -- -include::{ocis_services_raw_url}{service_url_component}{ocis_services_final_path}adoc/{service_name}_configvars.adoc[] +include::example${ocis_helpers_extended}{service_name}_configvars.adoc[] -- ==== -end::envvars-only[] +end::extended-only[] diff --git a/content/ocis/8.3/modules/admin/partials/multi-location/compose-version.adoc b/content/ocis/8.3/modules/admin/partials/multi-location/compose-version.adoc index 81006a4..9a37a68 100644 --- a/content/ocis/8.3/modules/admin/partials/multi-location/compose-version.adoc +++ b/content/ocis/8.3/modules/admin/partials/multi-location/compose-version.adoc @@ -1,28 +1,25 @@ //// -depending of the version (production/rolling), attributes get defined dynamically +depending of the version (stable/development), attributes get defined dynamically -if the branch is master, identified via the component version equals 'next', we have a rolling release -if the branch is anything else, it is a production version and has its own branch +if the branch is master, identified via attribute page-component-version-is-prerelease, we must point to the latest stable +if the branch is anything else, it is a stable version and and can be used as is (stable-x.y) -the outcome guarantees that we always access the correct paths to get or reference source files from - -ocis_repo_url_component: defined in antora.yml: is either master or a branched version -ocis_repo_url_stable: defined in antora.yml: is always the latest stable branch of this version -antora-component-version: intrinsic via antora.yml: is either next or a branched version like 7.2 +the outcome guarantees that we always access the correct paths to get or reference to source files from //// -// first we define the default -// production (because it has an own doc branch) -// url is either master or like stable-7.2 -:compose_version: {ocis_repo_url_component} -:version-type: production +// first we define the default which is stable +// url assembled points to any valid stable-x.y +:compose_version: stable-{page-component-version} +:tab_text: {page-component-version} +:env_tab_text: {page-component-version} +:ocis_git_version: stable-{page-component-version} // but: -// if it is the master branch, defined as next, we need to redefine to a stable branch +// if it is the prerelease (master branch == development), we need to redefine to the latest stable branch // master may contain non functional data -// latest-ocis-version is defined in global-attributes.yml: 7.2 or 7.1 -// the file is included via an extension -ifeval::["{antora-component-version}" == "next"] -:compose_version: {ocis_repo_url_stable} -:version-type: rolling +ifdef::page-component-version-is-prerelease[] +:compose_version: stable-{page-component-latest-version} +:tab_text: {page-component-latest-version} +:env_tab_text: master +:ocis_git_version: master endif::[] diff --git a/content/ocis/8.3/modules/admin/partials/multi-location/tab-text.adoc b/content/ocis/8.3/modules/admin/partials/multi-location/tab-text.adoc deleted file mode 100644 index 3317e57..0000000 --- a/content/ocis/8.3/modules/admin/partials/multi-location/tab-text.adoc +++ /dev/null @@ -1,12 +0,0 @@ -//// -the tab text printed depends on if you are on master, then it is 'master + Rolling ' -or it is the value of the name as defined in antora.yml -//// - -// compute the correct tab text -:tab_text: {service_tab_text} - -// we do not make rolling releases anymore, keeping the code if that changes -// ifeval::["{service_tab_text}" == "master"] -// :tab_text: {service_tab_text} + Rolling {ocis-rolling-version} -// endif::[] diff --git a/test/go-redirect.test.js b/extension-tests/go-redirect.test.js similarity index 100% rename from test/go-redirect.test.js rename to extension-tests/go-redirect.test.js diff --git a/test/latest-alias.test.js b/extension-tests/latest-alias.test.js similarity index 100% rename from test/latest-alias.test.js rename to extension-tests/latest-alias.test.js diff --git a/test/helpers/latest-versions.js b/extension-tests/latest-versions.js similarity index 100% rename from test/helpers/latest-versions.js rename to extension-tests/latest-versions.js diff --git a/test/next-alias.test.js b/extension-tests/next-alias.test.js similarity index 100% rename from test/next-alias.test.js rename to extension-tests/next-alias.test.js diff --git a/test/page-aliases.test.js b/extension-tests/page-aliases.test.js similarity index 100% rename from test/page-aliases.test.js rename to extension-tests/page-aliases.test.js diff --git a/extension-tests/prerelease-attribute.test.js b/extension-tests/prerelease-attribute.test.js new file mode 100644 index 0000000..038a322 --- /dev/null +++ b/extension-tests/prerelease-attribute.test.js @@ -0,0 +1,148 @@ +'use strict' + +// Guards for antora-extensions/prerelease-attribute.js, which sets the AsciiDoc +// attribute page-component-version-is-prerelease on every page of a component +// version marked `prerelease` in its antora.yml. +// +// The extension only rewrites componentVersion.asciidoc, so a fake content catalog +// exercises it fully -- no built site needed. The one thing worth guarding beyond +// the flag itself is that the shared siteAsciiDocConfig object is never mutated: +// Antora hands that very object to every component version whose descriptor +// defines no attributes of its own, so an in-place write would mark the whole site +// as prerelease. + +const test = require('node:test') +const assert = require('node:assert/strict') + +const { register } = require('../antora-extensions/prerelease-attribute') + +const ATTRIBUTE = 'page-component-version-is-prerelease' + +const componentVersion = (name, version, extra = {}) => + Object.assign({ name, version, displayVersion: version || 'default' }, extra) + +// The slice of Antora's ContentCatalog the extension reads. +const fakeCatalog = (components) => ({ getComponents: () => components }) + +// Run the extension and return the warnings it logged. +function run (components, siteAsciiDocConfig) { + const warnings = [] + const handlers = {} + register.call({ + once: (event, fn) => (handlers[event] = fn), + getLogger: () => ({ warn: (...args) => warnings.push(args) }), + }) + handlers.contentClassified({ contentCatalog: fakeCatalog(components), siteAsciiDocConfig }) + return warnings +} + +const attrs = (cv) => cv.asciidoc?.attributes || {} + +test('a prerelease version gets the attribute, a release version does not', () => { + const dev = componentVersion('ocis', '8.3', { prerelease: true, asciidoc: { attributes: {} } }) + const release = componentVersion('ocis', '8.2', { asciidoc: { attributes: {} } }) + run([{ name: 'ocis', versions: [dev, release], latest: release, latestPrerelease: dev }], { attributes: {} }) + assert.equal(attrs(dev)[ATTRIBUTE], '', 'the prerelease version must carry the flag') + assert.ok(!(ATTRIBUTE in attrs(release)), 'the release version must not carry the flag') +}) + +test('a string prerelease value still sets the flag to the empty string', () => { + // antora.yml may say `prerelease: Beta` instead of `true`; the attribute stays a + // flag either way -- the label belongs in page-component-display-version. + const beta = componentVersion('ocis', '9.0', { prerelease: 'Beta', asciidoc: { attributes: {} } }) + run([{ name: 'ocis', versions: [beta], latest: beta }], { attributes: {} }) + assert.equal(attrs(beta)[ATTRIBUTE], '') +}) + +test('existing component version attributes are preserved', () => { + const dev = componentVersion('ocis', '8.3', { + prerelease: true, + asciidoc: { attributes: { 'oc-version': '8.3' }, extensions: ['./asciidoc-extensions/tabs.js'] }, + }) + run([{ name: 'ocis', versions: [dev], latest: dev }], { attributes: {} }) + assert.equal(attrs(dev)['oc-version'], '8.3', 'component attributes must survive') + assert.deepEqual(dev.asciidoc.extensions, ['./asciidoc-extensions/tabs.js'], 'config keys must survive') +}) + +test('the shared site AsciiDoc config is not mutated', () => { + // Both versions inherit the site config object itself, which is what Antora does + // for a descriptor without an `asciidoc` key. + const siteAsciiDocConfig = { attributes: { 'site-title': 'ownCloud' } } + const dev = componentVersion('ocis', '8.3', { prerelease: true, asciidoc: siteAsciiDocConfig }) + const release = componentVersion('server', '11.0', { asciidoc: siteAsciiDocConfig }) + run( + [ + { name: 'ocis', versions: [dev], latest: dev }, + { name: 'server', versions: [release], latest: release }, + ], + siteAsciiDocConfig + ) + assert.deepEqual( + siteAsciiDocConfig, + { attributes: { 'site-title': 'ownCloud' } }, + 'the site config must come out untouched' + ) + assert.equal(attrs(dev)[ATTRIBUTE], '') + assert.equal(release.asciidoc, siteAsciiDocConfig, 'an untouched version must keep sharing the site config') +}) + +test('a component version without its own AsciiDoc config falls back to the site config', () => { + const siteAsciiDocConfig = { attributes: { 'site-title': 'ownCloud' } } + const dev = componentVersion('desktop', '7.2', { prerelease: true }) // no asciidoc key + run([{ name: 'desktop', versions: [dev], latest: dev }], siteAsciiDocConfig) + assert.equal(attrs(dev)[ATTRIBUTE], '') + assert.equal(attrs(dev)['site-title'], 'ownCloud', 'site attributes must not be dropped') +}) + +test('a hand-set flag on a release version is dropped and warned about', () => { + const release = componentVersion('ocis', '8.2', { asciidoc: { attributes: { [ATTRIBUTE]: '' } } }) + const warnings = run([{ name: 'ocis', versions: [release], latest: release }], { attributes: {} }) + assert.ok(!(ATTRIBUTE in attrs(release)), 'the derived attribute must win over a hand-set one') + assert.equal(warnings.length, 1, 'dropping a hand-set flag must be reported') + assert.match(warnings[0].join(' '), /prerelease/) +}) + +test('the versionless components (main, webui) are left alone', () => { + const siteAsciiDocConfig = { attributes: {} } + const webui = componentVersion('webui', '', { asciidoc: siteAsciiDocConfig }) + const warnings = run([{ name: 'webui', versions: [webui], latest: webui }], siteAsciiDocConfig) + assert.ok(!(ATTRIBUTE in attrs(webui))) + assert.deepEqual(warnings, []) +}) + +// The real content tree: every version marked `prerelease` in its antora.yml must +// end up with the flag, and no other version may. This is the mapping the +// extension is there to produce, checked against the descriptors on disk. +test('every prerelease version in content/ gets the flag, and only those', () => { + const fs = require('node:fs') + const path = require('node:path') + const CONTENT = path.join(__dirname, '..', 'content') + + const versions = [] // { component, version, prerelease } + for (const product of fs.readdirSync(CONTENT)) { + const productDir = path.join(CONTENT, product) + if (!fs.statSync(productDir).isDirectory()) continue + for (const entry of fs.readdirSync(productDir)) { + const descriptor = path.join(productDir, entry, 'antora.yml') + if (!fs.existsSync(descriptor)) continue // versionless: antora.yml sits one level up + const yaml = fs.readFileSync(descriptor, 'utf8') + versions.push({ component: product, version: entry, prerelease: /^prerelease:\s*(true|\S+)/m.test(yaml) }) + } + } + assert.ok(versions.some((v) => v.prerelease), 'no prerelease version found in content/ -- test is not exercising anything') + + const catalogVersions = versions.map(({ component, version, prerelease }) => + componentVersion(component, version, Object.assign({ asciidoc: { attributes: {} } }, prerelease && { prerelease })) + ) + const byComponent = new Map() + catalogVersions.forEach((cv) => { + if (!byComponent.has(cv.name)) byComponent.set(cv.name, { name: cv.name, versions: [] }) + byComponent.get(cv.name).versions.push(cv) + }) + byComponent.forEach((component) => (component.latest = component.versions[0])) + run([...byComponent.values()], { attributes: {} }) + + const flagged = catalogVersions.filter((cv) => ATTRIBUTE in attrs(cv)).map((cv) => `${cv.name}/${cv.version}`) + const expected = versions.filter((v) => v.prerelease).map((v) => `${v.component}/${v.version}`) + assert.deepEqual(flagged.sort(), expected.sort()) +}) diff --git a/test/static-files.test.js b/extension-tests/static-files.test.js similarity index 100% rename from test/static-files.test.js rename to extension-tests/static-files.test.js diff --git a/global-attributes.yml b/global-attributes.yml index 149dee9..a1f5c53 100644 --- a/global-attributes.yml +++ b/global-attributes.yml @@ -48,16 +48,13 @@ std-port-mysql: '3306' std-port-redis: '6379' # ocis - # branch versions, also used to assemble branch names in ocis - latest-ocis-version: '8.2' # + # branch versions mainly used outside ocis except versions up to including 8.0, can be removed after removing 8.0 + latest-ocis-version: '8.2' previous-ocis-version: '8.1' - # Versions mainly for printing like in docs-main release info and in docs-ocis to define the latest production version. - # Versions in the ocis docs need to be defined in the branch specific docs-ocis/antora.yaml file. - # To do so, change the values in the branch of docs-ocis/antora.yml like service_xxx and compose_xxx. + # versions for printing in component main, release info to define the latest/former production version. ocis-actual-version: '8.2.0' ocis-former-version: '8.1.0' - ocis-compiled: '2026-08-10 00:00:00 +0000 UTC' - ocis-downloadpage-url: 'https://download.owncloud.com/ocis/ocis' + # webui (versionless component in the monorepo; no @version qualifier) # desktop latest-desktop-version: '7.1' diff --git a/site.yml b/site.yml index 82d4f5f..cf1698f 100644 --- a/site.yml +++ b/site.yml @@ -73,6 +73,12 @@ antora: - ./antora-extensions/comp-version.js - ./antora-extensions/latest-alias.js - ./antora-extensions/next-alias.js + # Antora derives page-component-version-is-latest but has no prerelease + # counterpart; this adds page-component-version-is-prerelease, set on every + # page of a version marked `prerelease` in its antora.yml (ocis 8.3, + # desktop 7.2, android 4.8 today), so content can branch on "this is the dev + # line" without hard-coding a version number. + - ./antora-extensions/prerelease-attribute.js - require: ./antora-extensions/load-global-site-attributes.js attributefile: ./global-attributes.yml enabled: true