RHIDP-8635 - Comprehensive documentation for developers on adding localization support to custom plugins

.vale-styles/config/vocabularies/RHDH/accept.txt

@@ -1 +1,6 @@
+cron
+Entra
+IdP
+Operator
+MSGraph
 scaffolder

.vale.ini

@@ -23,3 +23,4 @@ BasedOnStyles = RedHat,DeveloperHub,AsciiDocDITA
 AsciiDocDITA.AttributeReference = NO
 AsciiDocDITA.ShortDescription = NO
 AsciiDocDITA.CrossReference = NO
+AsciiDocDITA.ConditionalCode = NO

artifacts/attributes.adoc

@@ -12,21 +12,21 @@
 :product-very-short: RHDH
 :product-local: Red Hat Developer Hub Local
 :product-local-very-short: RHDH Local
-:product-version: 1.7
-:product-bundle-version: 1.7.0
-:product-chart-version: 1.7.0
-:product-backstage-version: 1.39.1
-:product-version-next: 1.7
+:product-version: 1.8
+:product-bundle-version: 1.8.0
+:product-chart-version: 1.8.0
+:product-backstage-version: 1.42.5
+:product-version-next: 1.9
 :product-custom-resource-type: Backstage
 :product-docs-url: https://docs.redhat.com/en/documentation/red_hat_developer_hub
 :product-docs-link: link:{product-docs-url}/{product-version}
 :backstage: Backstage
 // Minimum and current latest supported versions
 :ansible-automation-platform-version: 2.4
 :keycloak-version: 26.0
-:kubernetes-version: 1.24
-:ocp-version-min: 4.14
-:ocp-version: 4.18
+:kubernetes-version: 1.29
+:ocp-version-min: 4.16
+:ocp-version: 4.19
 :osd-version: 4
 :rhoserverless-version: 1.36
 
@@ -151,6 +151,8 @@
 :observability-category-link: {product-docs-link}/#Observability
 :ocp-docs-link: link:https://docs.redhat.com/en/documentation/openshift_container_platform/{ocp-version}
 :odf-docs-link: link:https://docs.redhat.com/en/documentation/red_hat_openshift_data_foundation/{ocp-version}
+:orchestrator-book-link: {product-docs-link}/html-single/orchestrator_in_red_hat_developer_hub/index
+:orchestrator-book-title: Orchestrator in {product}
 :osd-docs-link: link:https://docs.redhat.com/en/documentation/openshift_dedicated/{osd-version}
 :release-notes-book-link: {product-docs-link}/html-single/red_hat_developer_hub_release_notes/index
 :release-notes-book-title: {product} release notes

assemblies/assembly-authenticating-with-the-guest-user.adoc

@@ -3,8 +3,7 @@
 [id="authenticating-with-the-guest-user_{context}"]
 = Authenticating with the Guest user
 
-To explore {product-short} features, you can skip configuring authentication and authorization.
-You can configure {product-short} to log in as a Guest user and access {product-short} features.
+For trial or non-production environments, you can enable guest access to skip configuring authentication and authorization and explore {product-short} features.
 
 include::modules/authentication/proc-authenticationg-with-the-guest-user-on-an-operator-based-installation.adoc[leveloffset=+1]
 

assemblies/assembly-building-and-deploying-serverless-workflows.adoc

@@ -0,0 +1,45 @@
+:_mod-docs-content-type: ASSEMBLY
+
+ifdef::context[]
+[id="assembly-building-and-deploying-serverless-workflows"]
+endif::[]
+:context: orchestrator-rhdh
+= Build and deploy serverless workflows
+
+To deploy a workflow and make it available in the Orchestrator plugin, follow these main steps:
+
+* Building workflow images
+* Generating workflow manifests
+* Deploying workflows to a cluster
+
+This process moves the workflow from your local machine to deployment on a cluster.
+
+// why build workflow images
+include::modules/orchestrator/con-benefits-of-workflow-images.adoc[leveloffset=+1]
+
+// project structure
+include::modules/orchestrator/con-project-structure-overview.adoc[leveloffset=+2]
+
+// creating and running workflows locally
+include::modules/orchestrator/proc-creating-and-running-workflows.adoc[leveloffset=+2]
+
+// building locally and generating artifacts
+include::modules/orchestrator/proc-building-locally.adoc[leveloffset=+1]
+
+// the script and its uses
+include::modules/orchestrator/con-build-sh-script-and-its-uses.adoc[leveloffset=+2]
+
+// environment variables supported by the script
+include::modules/orchestrator/con-environment-variables-supported-by-the-build-script.adoc[leveloffset=+2]
+
+// required tools
+include::modules/orchestrator/con-required-tools.adoc[leveloffset=+2]
+
+// building the 01_basic workflow
+include::modules/orchestrator/proc-building-the-01-basic-workflow.adoc[leveloffset=+2]
+
+// generated workflow manifests
+include::modules/orchestrator/con-generated-workflow-manifests.adoc[leveloffset=+1]
+
+// deploy workflows on a cluster
+include::modules/orchestrator/proc-deploying-workflows-on-a-cluster.adoc[leveloffset=+1]

assemblies/assembly-configuring-a-proxy.adoc

@@ -1,4 +1,5 @@
 :_mod-docs-content-type: ASSEMBLY
+:previouscontext: {context}
 :context: running-behind-a-proxy
 
 [id="{context}"]
@@ -22,3 +23,5 @@ include::modules/configuring-a-proxy/proc-configuring-proxy-in-operator-deployme
 
 include::modules/configuring-a-proxy/proc-configuring-proxy-in-helm-deployment.adoc[leveloffset=+1]
 
+:context: {previouscontext}
+!:previouscontext:

assemblies/assembly-configuring-external-postgresql-databases.adoc

@@ -1,4 +1,5 @@
 :_mod-docs-content-type: ASSEMBLY
+:previouscontext: {context}
 :context: configuring-external-postgresql-databases
 
 [id="{context}"]
@@ -22,3 +23,5 @@ include::modules/configuring-external-databases/proc-configuring-postgresql-inst
 
 include::modules/configuring-external-databases/proc-migrating-databases-to-an-external-server.adoc[leveloffset=+1]
 
+:context: {previouscontext}
+!:previouscontext:

assemblies/assembly-configuring-high-availability.adoc

@@ -1,4 +1,5 @@
 :_mod-docs-content-type: ASSEMBLY
+:previouscontext: {context}
 :context: HighAvailability
 
 [id="{context}"]
@@ -28,3 +29,6 @@ As an administrator, you can configure high availability by adjusting replica va
 include::modules/configuring-high-availability/proc-configuring-high-availability-in-rhdh-operator-deployment.adoc[leveloffset=+1]
 
 include::modules/configuring-high-availability/proc-configuring-high-availability-in-rhdh-helm-chart-deployment.adoc[leveloffset=+1]
+
+:context: {previouscontext}
+!:previouscontext:

assemblies/assembly-configuring-templates.adoc

@@ -19,6 +19,7 @@ include::modules/customizing-templates/proc-creating-a-new-software-component-us
 include::modules/customizing-templates/proc-searching-and-filtering-software-templates.adoc[leveloffset=+1]
 include::modules/customizing-templates/proc-adding-templates.adoc[leveloffset=+1]
 include::modules/customizing-templates/proc-versioning-software-templates.adoc[leveloffset=+1]
+include::modules/customizing-templates/proc-enabling-software-template-version-update-notifications.adoc[leveloffset=+1]
 
 [role="_additional-resources"]
 .Additional resources

assemblies/assembly-configuring-the-quickstarts.adoc

@@ -8,4 +8,6 @@ include::modules/configuring-the-quickstarts/con-about-quickstarts.adoc[leveloff
 
 include::modules/configuring-the-quickstarts/proc-customize-rhdh-quickstart.adoc[leveloffset=+1]
 
+include::modules/configuring-the-quickstarts/proc-disabling-rhdh-quickstart.adoc[leveloffset=+2]
+
 include::modules/configuring-the-quickstarts/proc-starting-and-completing-modules-in-quickstarts.adoc[leveloffset=+1]

assemblies/assembly-customizing-the-appearance.adoc

@@ -4,13 +4,15 @@
 [id="{context}"]
 = Customizing {product} appearance
 
+By modifying the visual aspects of the interface, organizations can align {product} with their branding guidelines and improve the overall user experience.
+
 The following default theme configurations are available for {product}:
 
 The {product} theme:: Default theme configurations to make your developer portal look like a standard {product} instance. For more information, see xref:ref-customize-rhdh-default-rhdh_{context}[]
 
 The Backstage theme:: Default theme configurations to make your developer portal look like a standard Backstage instance. For more information, see xref:ref-customize-rhdh-default-backstage_{context}[]
 
-You can change or disable particular parameters in a default theme or create a fully customized theme by modifying the `app-config-rhdh.yaml` file. From the `app-config-rhdh.yaml` file, you can customize common theme components, including the following:
+You can change or disable particular parameters in a default theme or create a fully customized theme by modifying the `app-config-rhdh.yaml` file. From the `app-config-rhdh.yaml` file, you can customize common theme components, including the following components:
 
 * Company name and logo
 * Font color, size, and style of text in paragraphs, headings, headers, and buttons
@@ -22,11 +24,10 @@ You can also customize some components from the {product-short} GUI, such as the
 
 include::modules/customizing-the-appearance/proc-customize-rhdh-theme-mode.adoc[leveloffset=+1]
 
-
 include::modules/customizing-the-appearance/proc-customize-rhdh-branding-logo.adoc[leveloffset=+1]
 
 
-include::modules/customizing-the-appearance/con-customize-rhdh-sidebar-menuitems.adoc[leveloffset=+1]
+include::modules/customizing-the-appearance/con-about-rhdh-sidebar-menuitems.adoc[leveloffset=+1]
 
 include::modules/customizing-the-appearance/proc-customize-rhdh-sidebar-menuitems.adoc[leveloffset=+2]
 

assemblies/assembly-enabling-authentication-with-github.adoc

@@ -0,0 +1,11 @@
+:_mod-docs-content-type: ASSEMBLY
+:optional-steps: enable
+
+[id='enabling-authentication-with-github']
+= Enabling authentication with GitHub
+
+include::modules/authentication/proc-enabling-user-authentication-with-github.adoc[leveloffset=+1]
+
+
+include::modules/authentication/proc-enabling-user-authentication-with-github-as-an-auxiliary-authentication-provider.adoc[leveloffset=+1]
+

assemblies/assembly-enabling-authentication-with-mandatory-steps-only.adoc

@@ -0,0 +1,20 @@
+:_mod-docs-content-type: ASSEMBLY
+:optional-steps: disable
+
+[id='enabling-authentication-with-mandatory-steps-only']
+= Enabling authentication in {product} (with mandatory steps only)
+
+include::modules/authentication/con-understanding-authentication-and-user-provisioning.adoc[leveloffset=+1]
+
+
+include::assembly-authenticating-with-the-guest-user.adoc[leveloffset=+1]
+
+
+include::modules/authentication/proc-enabling-user-authentication-with-rhbk.adoc[leveloffset=+1]
+
+
+include::modules/authentication/proc-enabling-user-authentication-with-github.adoc[leveloffset=+1]
+
+
+include::modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc[leveloffset=+1]
+

assemblies/assembly-enabling-authentication.adoc

@@ -1,11 +1,9 @@
 :_mod-docs-content-type: ASSEMBLY
+:optional-steps: enable
 
 [id='enabling-authentication']
 = Enabling authentication in {product}
 
-
-
-
 include::modules/authentication/con-understanding-authentication-and-user-provisioning.adoc[leveloffset=+1]
 
 
@@ -15,7 +13,7 @@ include::assembly-authenticating-with-the-guest-user.adoc[leveloffset=+1]
 include::assembly-authenticating-with-rhbk.adoc[leveloffset=+1]
 
 
-include::modules/authentication/proc-enabling-user-authentication-with-github.adoc[leveloffset=+1]
+include::assembly-enabling-authentication-with-github.adoc[leveloffset=+1]
 
 
 include::modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc[leveloffset=+1]

assemblies/assembly-localization-in-rhdh.adoc

@@ -0,0 +1,14 @@
+:_mod-docs-content-type: ASSEMBLY
+
+[id="assembly-localization-in-rhdh_{context}"]
+= Localization in {product}
+
+include::modules/customizing-the-appearance/proc-enabling-localization-in-rhdh.adoc[leveloffset=+1]
+
+include::modules/customizing-the-appearance/proc-overriding-translations.adoc[leveloffset=+2]
+
+include::modules/customizing-the-appearance/proc-select-rhdh-language.adoc[leveloffset=+1]
+
+include::modules/customizing-the-appearance/con-language-persistence.adoc[leveloffset=+2]
+
+include::modules/customizing-the-appearance/proc-adding-localization-to-custom-plugins.adoc[leveloffset=+1]

assemblies/assembly-orchestrator-rhdh.adoc

@@ -27,13 +27,16 @@ To start using Orchestrator in {product-very-short}, you must:
 * Import the Orchestrator software templates into the {product} catalog
 
 // orchestrator architecture
-include::modules/orchestrator/con-supported-architecture-for-orchestrator.adoc[leveloffset=+1]
+include::modules/orchestrator/con-architecture-overview.adoc[leveloffset=+1]
+
+// compatibility guide for {product} Orchestrator
+include::modules/orchestrator/ref-compatibility-guide-for-orchestrator.adoc[leveloffset=+1]
 
 // provisioning plugin dependencies
 include::modules/orchestrator/con-orchestrator-plugin-dependencies-operator.adoc[leveloffset=+1]
 
-// installing the components for the orchestrator plugin
-include::modules/orchestrator/con-orchestrator-plugin-components.adoc[leveloffset=+1]
+// enabling orchestrator plugins components
+include::modules/orchestrator/proc-enabling-orchestrator-plugins-components.adoc[leveloffset=+1]
 
 // Orchestrator Infrastructure for {product} Helm chart
 include::modules/orchestrator/proc-helm-install-components-orchestrator-plugin.adoc[leveloffset=+2]
@@ -42,5 +45,4 @@ include::modules/orchestrator/proc-helm-install-components-orchestrator-plugin.a
 include::modules/orchestrator/proc-manual-install-components-orchestrator-plugin.adoc[leveloffset=+2]
 
 // {product-very-short} helper script
-include::modules/orchestrator/proc-helper-script-overview.adoc[leveloffset=+2]
-
+include::modules/orchestrator/proc-helper-script-overview.adoc[leveloffset=+2]

assemblies/assembly-provisioning-a-custom-configuration.adoc

@@ -1,4 +1,5 @@
 :_mod-docs-content-type: ASSEMBLY
+:previouscontext: {context}
 :context: provisioning-and-using-your-custom-configuration
 
 [id="{context}"]
@@ -27,3 +28,5 @@ include::modules/configuring/proc-mounting-additional-files-in-your-custom-confi
 
 include::modules/configuring/proc-using-the-helm-chart-to-run-rhdh-with-your-custom-configuration.adoc[leveloffset=+1]
 
+:context: {previouscontext}
+!:previouscontext:

assemblies/dynamic-plugins/assembly-configuring-rhdh-plugins.adoc

@@ -15,17 +15,24 @@ include::assembly-enabling-configuring-jfrog.adoc[leveloffset=+1]
 // Keycloak - modularized
 include::assembly-enabling-configuring-keycloak.adoc[leveloffset=+1]
 
+
 // Nexus - modularized
 include::assembly-enabling-configuring-nexus.adoc[leveloffset=+1]
 
 // Tekton - modularized
 include::../../modules/dynamic-plugins/proc-enabling-the-tekton-plugin.adoc[leveloffset=+1]
 
-// Topology - no-change
-include::assembly-install-topology-plugin.adoc[leveloffset=+1]
+// Topology
+include::../dynamic-plugins/assembly-install-topology-plugin.adoc[leveloffset=+1]
+
+// Bulk Importing
+include::../assembly-bulk-importing-from-github.adoc[leveloffset=+1]
 
+// ServiceNow
 include::../assembly-using-servicenow.adoc[leveloffset=+1]
 
+// Kubernetes Custom Actions
 include::../assembly-using-kubernetes-custom-actions.adoc[leveloffset=+1]
 
-include::../../modules/dynamic-plugins/proc-overriding-core-backend-services.adoc[leveloffset=+1]
+// Overriding Core Backend Service Configuration
+include::../modules/dynamic-plugins/proc-overriding-core-backend-services.adoc[leveloffset=+1]

assemblies/dynamic-plugins/assembly-rhdh-installing-dynamic-plugins.adoc

@@ -38,6 +38,10 @@ include::../modules/dynamic-plugins/ref-rh-tech-preview-plugins.adoc[leveloffset
 [id="rhdh-community-plugins"]
 include::../modules/dynamic-plugins/ref-community-plugins.adoc[leveloffset=+4]
 
+// Deprecated plugins
+[id="rhdh-deprecated-plugins"]
+include::../modules/dynamic-plugins/ref-deprecated-plugins.adoc[leveloffset=+4]
+
 // Red Hat compatible plugins
 [id="rhdh-compatible-plugins"]
 include::../modules/dynamic-plugins/ref-rh-compatible-plugins.adoc[leveloffset=+1]

modules/authentication/con-understanding-authentication-and-user-provisioning.adoc

@@ -2,8 +2,7 @@
 
 = Understanding authentication and user provisioning
 
-This module provides an overview of how authentication and user provisioning function within {product}.
-Learn about the process from creating user and group entities in the software catalog to user sign-in, and how authentication and catalog plugins enable each step.
+Learn about the authentication process from creating user and group entities in the software catalog to user sign-in, and how authentication and catalog plugins enable each step.
 Understanding this process is essential for successfully configuring your {product-short} instance, securing access through authorization, and enabling features that rely on synchronized user and group data.
 
 To fully enable catalog features, provision user and group data from the Identity Provider to the {product-short} software catalog.
@@ -18,21 +17,29 @@ On successful authentication, the {product-short} authentication plugin, configu
 
 Configuring authentication and user provisioning is critical for several reasons.
 
-* It secures your {product-short} instance by ensuring only authenticated users can gain access.
-* It enables authorization by allowing you to define access controls based on user and group memberships synchronized from your IdP.
+* Securing your {product-short} instance by ensuring only authenticated users can gain access.
+* Enabling authorization by allowing you to define access controls based on user and group memberships synchronized from your IdP.
 * Provisioning user and group data to the catalog is necessary for various catalog features that rely on understanding entity ownership and relationships between users, groups, and software components.
-Without this provisioning step, features like displaying who owns a component in the catalog may not function correctly.
++
+[IMPORTANT]
+====
+Without this provisioning step, features such as displaying who owns a catalog entity might not function correctly.
+====
 
 [TIP]
 ====
 To explore {product-short} features in a non-production environment, you can:
 
 * To use {product-short} without external IdP, enable the guest user to skip configuring authentication and authorization, log in as the guest user, and access all {product-short} features.
 
-* To use {product-short} without authorization policies and features relying on the software catalog, you can enable the `dangerouslyAllowSignInWithoutUserInCatalog` resolver option. This setting bypasses the check requiring a user to be in the catalog but still enforces authentication.
+* To use {product-short} without authorization policies and features relying on the software catalog, you can enable the `dangerouslyAllowSignInWithoutUserInCatalog` resolver option.
+This setting bypasses the check requiring a user to be in the catalog but still enforces authentication.
 ====
 
 [IMPORTANT]
 ====
-{product-short} uses a one-way synchronization model, where user and group data flow from your Identity Provider to the {product-short} software catalog. As a result, deleting users or groups manually through the {product-short} Web UI or REST API might be ineffective or cause inconsistencies, since those entities will be recreated during the next ingestion.
+{product-short} uses a one-way synchronization model, where user and group data flow from your Identity Provider to the {product-short} software catalog.
+As a result,
+deleting users or groups manually through the {product-short} Web UI or REST API might be ineffective or cause inconsistencies,
+since {product-short} will create those entities again during the next import.
 ====