[DITA] March report fixes for MTA

[mpershina]

Report with all the comments: https://docs.google.com/spreadsheets/d/1ICPE3F3zbHH4Gy6MvI1WIvR4A5_LZIEV_s0iI6kwttw/edit?gid=2139460735#gid=2139460735

Previews

• CLI

  • Chapter 3. Analyzing Java applications with MTA command-line interface
  • Chapter 4. Analyzing applications written in languages other than Java with MTA command-line interface

• Install

  • 3.2. Red Hat Build of Keycloak
  • 1.1. MTA features
  • 1.2. MTA rules
  • 1.3. MTA tools
  • 3.2.1. Accessing the RHBK Admin Console

• UI

  • 6.2. MTA assessment questionnaires
  • Chapter 2. Configuring the migration toolkit for applications instance environment
  • Chapter 7. Tagging applications with MTA
  • 6.1. The Assessment module features

• RDG

  • Chapter 8. Rulesets
  • Chapter 6. Rule actions
  • Chapter 3. Providers and rule conditions
  • Chapter 1. Introduction to rules
  • 1.1. The MTA rules
  • 3.1. Provider capabilities in custom rules
  • 3.3. The builtin provider
  • 8.1. Creating and using a custom ruleset
  • 3.6. C# provider
  • 3.5. Go provider
  • 3.4. Java provider
  • 2.1. Rule metadata structure

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Consolidated and restructured AsciiDoc documentation across the repository: removed multiple standalone topics and template includes, standardized and moved inline xrefs into _additional-resources blocks, reformatted numerous rules/provider YAML docs, and clarified CLI containerless-analysis and Keycloak wording.

Changes

Cohort / File(s)	Summary
Deleted topics & templates docs/topics/cli-args.adoc, docs/topics/about-home-var.adoc, docs/topics/available-openrewrite-recipes.adoc, docs/topics/developer-preview-feature.adoc, docs/topics/rules-important-links.adoc, docs/topics/templates/developer-preview.adoc, docs/topics/templates/technology-preview-admonition.adoc, docs/topics/rules-development/technology-preview.adoc, docs/topics/rules-development/developer-preview-admonition.adoc, docs/topics/rules-development/rules-guide-intro.adoc	Removed multiple standalone documentation and include/template modules (CLI args, env var guidance, OpenRewrite recipes, preview admonitions, and other topic stubs).
CLI guides assemblies/cli-guide/assembly_analyzing-applications-mta-cli.adoc, assemblies/cli-guide/assembly_analyzing-nonjava-applications.adoc	Consolidated analyzer-lsp/containerless messaging, removed duplicate phrasing, shortened version qualifiers, clarified containerless applies to Java only, and added/adjusted cross-reference and formatting.
UI guides & assessment/tagging assemblies/ui-guide/assembly_assessment-questionnaires.adoc, assemblies/ui-guide/assembly_configuring-mta-instance-environment.adoc, assemblies/ui-guide/assembly_tagging-applications.adoc, docs/topics/mta-ui/con_assessment-module-features.adoc, docs/topics/mta-web-applying-assessments-to-other-apps.adoc	Replaced inline xrefs with generic wording or centralized _additional-resources blocks, removed a "Next steps" section, renamed a document attribute, and added an abstract role marker.
Installation & Keycloak / tools assemblies/mta-install-title/assembly_red-hat-build-of-keycloak.adoc, docs/topics/mta-install/con_mta-features.adoc, docs/topics/mta-install/con_mta-rules.adoc, docs/topics/mta-install/con_mta-tools.adoc, docs/topics/mta-install/proc_accessing-rhbk-admin-console.adoc	Removed explicit version qualifiers and direct external Keycloak links, consolidated per-tool “For more information” lines into _additional-resources blocks, and updated Red Hat Build of Keycloak references.
Rules development & providers assemblies/rules-development-guide/assembly_rule-yaml-conditions.adoc, assemblies/rules-development-guide/assembly_rule-rulesets.adoc, assemblies/rules-development-guide/assembly_rule-yaml-actions.adoc, docs/topics/rules-development/..., docs/topics/rules-development/con_provider-capability-in-custom-rules.adoc	Replaced inline provider-capability section with a new included topic, adjusted YAML/provider capability and metadata formatting across several rule docs, moved inline links into _additional-resources blocks, and added the new provider-capability concept page.
Formatting/markup tweaks docs/topics/rules-development/yaml-*.adoc (multiple), docs/topics/rules-development/yaml-rule-metadata.adoc, docs/topics/rules-development/yaml-rulesets.adoc, docs/topics/rules-development/yaml-rule-actions.adoc	Refactored AsciiDoc formatting/markup for capability and metadata sections (definition lists, bullets, spacing), removed some trailing xref text and centralized those links into additional-resources blocks.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• MTA-6471 C# Provider Documentation #309: Edits overlap on provider/conditions content and the include used by rule YAML docs.
• CQA 2.1: Rules Development Guide Feb 26 #308: Overlapping changes to provider wording/formatting and assembly_rule-yaml-conditions.adoc.
• [MTA] Broken links fixes for MTA docs #328: Related changes to docs/topics/mta-install/con_mta-rules.adoc and resource/link restructuring.

Suggested reviewers

• anarnold97
• Pkylas007

Poem

🐰
I hopped through docs with quiet cheer,
Snipped links, aligned notes, made sections clear,
Moved resources into tidy stacks,
Left whitespace neat along my tracks,
A rabbit’s fix — the guides appear.

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Title check	❓ Inconclusive	The title '[DITA] March report fixes for MTA' is vague and generic, using non-descriptive terms like 'fixes' and 'March report' without conveying what specific changes or improvements are made to the MTA documentation.	Clarify the title to describe specific changes, such as 'Restructure documentation sections and remove outdated templates' or 'Update documentation architecture and remove deprecated preview templates'.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch March-dita-fixes

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@assemblies/ui-guide/assembly_tagging-applications.adoc`:
- Line 20: The sentence "You can either set an automated tagging or tag
applications manually." uses incorrect phrasing; change "set an automated
tagging" to a grammatically correct option such as "set up automated tagging" or
"use automated tagging" so the sentence reads e.g. "You can either set up
automated tagging or tag applications manually." Update the text in
assembly_tagging-applications.adoc accordingly.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 5e41f86f-3daa-49bb-98b5-30a6bf60d6e3

📥 Commits

Reviewing files that changed from the base of the PR and between a1ffd9b and 68eac5c.

📒 Files selected for processing (20)

• assemblies/cli-guide/assembly_analyzing-applications-mta-cli.adoc
• assemblies/cli-guide/assembly_analyzing-nonjava-applications.adoc
• assemblies/mta-install-title/assembly_red-hat-build-of-keycloak.adoc
• assemblies/ui-guide/assembly_assessment-questionnaires.adoc
• assemblies/ui-guide/assembly_configuring-mta-instance-environment.adoc
• assemblies/ui-guide/assembly_tagging-applications.adoc
• docs/topics/about-home-var.adoc
• docs/topics/available-openrewrite-recipes.adoc
• docs/topics/cli-args.adoc
• docs/topics/developer-preview-feature.adoc
• docs/topics/fork-ruleset-repo.adoc
• docs/topics/mta-install/con_mta-features.adoc
• docs/topics/mta-install/con_mta-rules.adoc
• docs/topics/mta-install/con_mta-tools.adoc
• docs/topics/mta-install/proc_accessing-rhbk-admin-console.adoc
• docs/topics/mta-ui/con_assessment-module-features.adoc
• docs/topics/mta-web-applying-assessments-to-other-apps.adoc
• docs/topics/rules-important-links.adoc
• docs/topics/templates/developer-preview.adoc
• docs/topics/templates/technology-preview-admonition.adoc

💤 Files with no reviewable changes (9)

• assemblies/ui-guide/assembly_configuring-mta-instance-environment.adoc
• docs/topics/fork-ruleset-repo.adoc
• docs/topics/about-home-var.adoc
• docs/topics/templates/technology-preview-admonition.adoc
• docs/topics/rules-important-links.adoc
• docs/topics/developer-preview-feature.adoc
• docs/topics/cli-args.adoc
• docs/topics/templates/developer-preview.adoc
• docs/topics/available-openrewrite-recipes.adoc

[coderabbitai]

Actionable comments posted: 1

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

docs/topics/rules-development/yaml-builtin-provider.adoc (1)

73-83: ⚠️ Potential issue | 🟡 Minor

Change hasTags: to builtin.hasTags: on line 80 for consistency.

The example uses hasTags: directly, but all other builtin capabilities in this file (builtin.file, builtin.filecontent, builtin.xml, builtin.json) and across the provider documentation are consistently namespaced with the builtin. prefix. Update the example to match this established pattern.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/topics/rules-development/yaml-builtin-provider.adoc` around lines 73 -
83, Update the example to use the namespaced capability name: replace the plain
hasTags usage with builtin.hasTags in the YAML snippet so it matches the rest of
the docs; locate the example showing "when: hasTags:" and change it to "when:
builtin.hasTags:" (referencing hasTags and builtin.hasTags to find the correct
block).

🧹 Nitpick comments (2)

docs/topics/rules-development/yaml-rule-metadata.adoc (1)

39-42: Remove leftover template guidance comments

The //// ... //// block looks like authoring-template guidance. Consider removing it before merge to keep the module source clean.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/topics/rules-development/yaml-rule-metadata.adoc` around lines 39 - 42,
Remove the leftover authoring-template guidance block that begins with "////"
and ends with "////" (the Optional. Delete if not used... Do not include
additional text.) from the YAML rule metadata topic; delete the entire comment
block and either replace it with the actual bulleted link list if relevant or
leave nothing in its place so no template guidance remains in the source.

docs/topics/rules-development/yaml-builtin-provider.adoc (1)

37-38: Remove the stray list marker before the xml capability heading.

Line 37 adds a standalone bullet (* \xml`) immediately before xml::`, which can render as an unintended extra list item and disrupt section formatting.

Proposed fix

-* `xml`
 `xml`::

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/topics/rules-development/yaml-builtin-provider.adoc` around lines 37 -
38, Remove the stray list marker that precedes the xml capability heading:
delete the standalone "* `xml`" bullet that appears immediately before the
"xml::" heading so only the "xml::" macro remains; update the section containing
the xml capability (the lines showing "* `xml`" and "xml::") to remove the
leading asterisk/bullet and ensure the "xml::" heading is the first token on
that line.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/topics/rules-development/yaml-rule-metadata.adoc`:
- Around line 31-35: Update the phrase describing the category metadata: locate
the bullet that starts with "`category` is severity of the issue for migration."
and change it to read "`category` is the severity of the issue for migration.
Values can be one of `mandatory`, `potential` or `optional`." so it reads
grammatically correct; the unique identifier to find is the `category` bullet in
the YAML rule metadata section.

---

Outside diff comments:
In `@docs/topics/rules-development/yaml-builtin-provider.adoc`:
- Around line 73-83: Update the example to use the namespaced capability name:
replace the plain hasTags usage with builtin.hasTags in the YAML snippet so it
matches the rest of the docs; locate the example showing "when: hasTags:" and
change it to "when: builtin.hasTags:" (referencing hasTags and builtin.hasTags
to find the correct block).

---

Nitpick comments:
In `@docs/topics/rules-development/yaml-builtin-provider.adoc`:
- Around line 37-38: Remove the stray list marker that precedes the xml
capability heading: delete the standalone "* `xml`" bullet that appears
immediately before the "xml::" heading so only the "xml::" macro remains; update
the section containing the xml capability (the lines showing "* `xml`" and
"xml::") to remove the leading asterisk/bullet and ensure the "xml::" heading is
the first token on that line.

In `@docs/topics/rules-development/yaml-rule-metadata.adoc`:
- Around line 39-42: Remove the leftover authoring-template guidance block that
begins with "////" and ends with "////" (the Optional. Delete if not used... Do
not include additional text.) from the YAML rule metadata topic; delete the
entire comment block and either replace it with the actual bulleted link list if
relevant or leave nothing in its place so no template guidance remains in the
source.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 3af91b05-d249-494c-93f1-b130fdc1a109

📥 Commits

Reviewing files that changed from the base of the PR and between 68eac5c and 87eec87.

📒 Files selected for processing (18)

• assemblies/rules-development-guide/assembly_rule-rulesets.adoc
• assemblies/rules-development-guide/assembly_rule-yaml-actions.adoc
• assemblies/rules-development-guide/assembly_rule-yaml-conditions.adoc
• assemblies/rules-development-guide/assembly_rules-introduction.adoc
• docs/topics/mta-intellij-plugin/what-is-the-toolkit.adoc
• docs/topics/rules-development/about-rules.adoc
• docs/topics/rules-development/con_provider-capability-in-custom-rules.adoc
• docs/topics/rules-development/developer-preview-admonition.adoc
• docs/topics/rules-development/rules-guide-intro.adoc
• docs/topics/rules-development/technology-preview.adoc
• docs/topics/rules-development/yaml-builtin-provider.adoc
• docs/topics/rules-development/yaml-condition-patterns.adoc
• docs/topics/rules-development/yaml-dotnet-provider.adoc
• docs/topics/rules-development/yaml-go-provider.adoc
• docs/topics/rules-development/yaml-java-provider.adoc
• docs/topics/rules-development/yaml-rule-actions.adoc
• docs/topics/rules-development/yaml-rule-metadata.adoc
• docs/topics/rules-development/yaml-rulesets.adoc

💤 Files with no reviewable changes (5)

• assemblies/rules-development-guide/assembly_rule-rulesets.adoc
• docs/topics/rules-development/rules-guide-intro.adoc
• docs/topics/rules-development/developer-preview-admonition.adoc
• assemblies/rules-development-guide/assembly_rules-introduction.adoc
• docs/topics/rules-development/technology-preview.adoc

✅ Files skipped from review due to trivial changes (9)

• assemblies/rules-development-guide/assembly_rule-yaml-actions.adoc
• docs/topics/rules-development/yaml-condition-patterns.adoc
• docs/topics/rules-development/yaml-rulesets.adoc
• docs/topics/rules-development/about-rules.adoc
• docs/topics/rules-development/yaml-go-provider.adoc
• docs/topics/rules-development/yaml-dotnet-provider.adoc
• docs/topics/rules-development/yaml-rule-actions.adoc
• docs/topics/rules-development/yaml-java-provider.adoc
• docs/topics/rules-development/con_provider-capability-in-custom-rules.adoc

[mpershina]

I don't think we need this note here as it's MTA 8 docs

[anarnold97]

No, and you have tidied this section up massively ... much cleaner, even if we have to return the note

[mpershina]

This seems to be out of place in this doc (it's also mentioned in the Install doc). Out of scope of this work, though. Will address it later.

[anarnold97]

can we comment it out here

create a ticket to relocate once this is merged. WDYT?

[mpershina]

Repeated in Creating and using a custom ruleset. Thus, removed here to avoid repetition.

[mpershina]

Caused the Block title issue. Moved as a separate module (con_provider-capability-in-custom-rules.adoc)

[coderabbitai]

🧹 Nitpick comments (1)

docs/topics/rules-development/yaml-rule-metadata.adoc (1)

39-42: Remove template-instruction comment block before merge.

This //// ... //// scaffold is template guidance and can be dropped to keep source docs clean.

✂️ Suggested cleanup

 [role="_additional-resources"]
 .Additional resources
-////
-Optional. Delete if not used.
-Provide a bulleted list of links and display text relevant to the assembly. These links can include `link:` and `xref:` macros. Do not include additional text.
-////
 * xref:yaml-rule-labels_rule-yaml-metadata[Rule labels]
 * xref:yaml-rule-categories_rule-yaml-metadata[Rule categories]

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/topics/rules-development/yaml-rule-metadata.adoc` around lines 39 - 42,
Remove the template scaffold block delimited by "////" that contains the line
"Optional. Delete if not used. Provide a bulleted list of links and display text
relevant to the assembly..."—delete the entire "//// ... ////" section so the
file no longer contains the template instruction comments and only keeps real
documentation content.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@docs/topics/rules-development/yaml-rule-metadata.adoc`:
- Around line 39-42: Remove the template scaffold block delimited by "////" that
contains the line "Optional. Delete if not used. Provide a bulleted list of
links and display text relevant to the assembly..."—delete the entire "//// ...
////" section so the file no longer contains the template instruction comments
and only keeps real documentation content.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 6456e559-8f03-4d70-84a9-de7847524671

📥 Commits

Reviewing files that changed from the base of the PR and between 71b2431 and 649eb1e.

📒 Files selected for processing (7)

• docs/topics/mta-ui/con_assessment-module-features.adoc
• docs/topics/rules-development/about-rules.adoc
• docs/topics/rules-development/yaml-builtin-provider.adoc
• docs/topics/rules-development/yaml-dotnet-provider.adoc
• docs/topics/rules-development/yaml-go-provider.adoc
• docs/topics/rules-development/yaml-java-provider.adoc
• docs/topics/rules-development/yaml-rule-metadata.adoc

✅ Files skipped from review due to trivial changes (4)

• docs/topics/rules-development/about-rules.adoc
• docs/topics/rules-development/yaml-go-provider.adoc
• docs/topics/rules-development/yaml-builtin-provider.adoc
• docs/topics/rules-development/yaml-dotnet-provider.adoc

🚧 Files skipped from review as they are similar to previous changes (1)

• docs/topics/mta-ui/con_assessment-module-features.adoc

[mpershina]

The title doesn't exist, thus removing

[mpershina]

Should first be checked; external links are not advised

[anarnold97]

agreed, let us check with Ramon if he really wants this link. If not, then we will delete

[anarnold97]

as i have unpublished 7.1.0 docs should we re-word this?

[anarnold97]

same as above here

[anarnold97]

Suggested change

	{ProductFullName} uses the Red Hat Build of Keycloak (RHBK) instance for user authentication and authorization. A RHBK instance is installed during the installation of the {ProductShortName} user interface. The {ProductShortName} Operator manages the RHBK instance and configures a dedicated realm with necessary roles and permissions.
	{ProductFullName} uses the Red Hat Build of Keycloak (RHBK) instance for user authentication and authorization. An RHBK instance is installed during the installation of the {ProductShortName} user interface. The {ProductShortName} Operator manages the RHBK instance and configures a dedicated realm with necessary roles and permissions.

A RHBK instance ... reads a bit weirdly

You have used the later, do you want to use that instead?

[anarnold97]

Suggested change

	To determine the readiness of your portfolio for modernization, use assessment questionnaires to provide the {ProductFullName} user interface (UI) with the details required for the migration process. The {ProductFullName} uses either default or custom assessment questionnaire.
	To determine the readiness of your portfolio for modernization, use assessment questionnaires to provide the {ProductFullName} user interface (UI) with the details required for the migration process. The {ProductFullName} uses either a default or custom assessment questionnaire.

[anarnold97]

Suggested change

	To determine the readiness of your portfolio for modernization, use assessment questionnaires to provide the {ProductFullName} user interface (UI) with the details required for the migration process. The {ProductFullName} uses either default or custom assessment questionnaire.
	To determine the readiness of your portfolio for modernization, use assessment questionnaires to provide the {ProductFullName} user interface (UI) with the details required for the migration process. The {ProductFullName} uses either the default questionnaire or a custom assessment questionnaire.

it just reads a bit strangely with the article

[anarnold97]

please, remind me to check the version of Keycloak as this might be out of date

[anarnold97]

Suggested change

	In a rule, the when block is where the conditions for matching the rule are specified. Each provider offers a series of capabilities to do matching.
	In a rule, the `when` block is where the conditions for matching the rule are specified. Each provider offers a series of capabilities to do matching.

it just feels like we should use some sort of formatting on the when clause

[anarnold97]

Suggested change

	The syntax for the when block is as follows: contains one condition, but that condition can have multiple conditions nested under it.
	The syntax of the when block is as follows: it contains a single condition, but that condition may have multiple conditions nested beneath it.

[anarnold97]

Suggested change

	Note that if you want to use the `--target` or `--source` option in the CLI, the engine will only select rules that match the label for that target. Therefore, make sure that you have added target or source labels on your rules.
	Note that if you want to use the `--target` or `--source` option in the CLI, the engine will only select rules that match the label for that target. Therefore, make sure that you have added target or source labels on your rules.

this reads like it should be an admonition. WDYT?

[anarnold97]

A few tiny things that i might correct

We need to check the Eclipse link with Ramon

However, looking at the previews, it is a really nice piece of work that is much cleaner.